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About This Book 


This book shows you how to develop, link, and execute programs in C language, 
using the Advanced Interactive Executive (AIX) Operating System. It describes the 
operating system dependencies of the language as well as the use of C language, 
related software utilities, and other program development tools. 


Who Should Read This Book 


This book is written for programmers who want to write application programs in C 
language that run on the AIX Operating System. 


What You Should Know 


You should have an intermediate to advanced understanding of the C programming 
language. You should also have a general understanding of programming concepts 
and terminology and some experience in writing programs. To get the most out of 
this book, you should know how to operate the Personal System/2, the RT PC, or 
the System/370. 


How to Use This Book 


This book is intended as a companion reference to the ALX C Language Reference. 
It is organized according to the general classes of elements that are used to construct 
programs in the C language. To locate specific topics, use the table of contents or 
the index. 


Highlighting 
This book uses different type styles to distinguish among certain kinds of informa- 
tion. General information is printed in the standard type style (for example, this 
sentence). 
The following type styles indicate other types of information: 


¢ Commands and keywords appear in bold type. 


e¢ Examples, words, and characters that must be entered literally appear in 
monospace type. 


e Variables appear in italics. 
e¢ New terms appear in bold italic type. 
Syntax Diagrams 
The following typographic conventions are used in the syntax diagrams: If you need 


information on how to read the syntax diagrams, refer to the ALY Commands 
Reference. 


¢ Syntactic categories appear between angle brackets (< >). 


e Alternative syntactic categories appear on separate lines. 


AIX is a trademark of International Business Machines Corporation. 
PS/2 is a registered trademark of International Business Machines Corporation. 
RT PC is a registered trademark of International Business Machines Corporation. 


System/370 is a trademark of International Business Machines Corporation. 
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Ellipses indicate that a preceding parameter can be repeated, for example: 
<object>... 


Variables that should be replaced by data objects in actual program statements 
appear in italics. 


An optional terminal symbol or non-terminal symbol is indicated by the 
notation: 
<object>... 
opt 


A syntactic definition is indicated by the name of the object being defined, fol- 
lowed by a colon, followed by the symbols that make up the object. Here is an 
example of the syntactic definition for a compound-statement: 


<compound-statement>: 
{ <declaration>... <statement>... } 
opt opt 


This specification states that a compound-statement is made up of a left brace, 
followed by one or more optional declarations and one or more optional state- 
ments followed by a right brace. Note that this definition provides for an empty 
compound statement. 


Brackets [ | indicate optional items and subscripts of an array. 


Braces { } enclose optional elements that can be repeated more than once. 


Related Publications 


For 


@ 
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additional information, you may want to refer to the following publications: 


AIX C Language Reference, SC23-2058, describes the C programming language 
and contains reference information for writing programs in C language that run 
on the AIX Operating System. 


AIX Operating System Commands Reference, SC23-2292 (Vol. 1) and SC23-2184 
(Vol. 2), lists and describes the AIX/370 and AIX PS/2 Operating System com- 
mands. 


AIX Programming Tools and Interfaces, SC23-2304, describes the programming 
environment of the ALIX Operating System and includes information about oper- 
ating system tools that are used to develop, compile, and debug programs. 


SAA Common Programming Interface C Reference, SC26-4353, describes each 
component of the common programming interface. 


AIX Operating System Technical Reference, SC23-2300 (Vol. 1) and SC23-2301 
(Vol. 2), describes the system calls and subroutines a programmer uses to write 
application programs. This book also provides information about the AIX 
Operating System file system, special files, miscellaneous files, and the writing of 
device drivers. 


Using the ALX Operating System, SC23-2291, shows the beginning user how to 
use AIX Operating System commands to do such basic tasks as log in and out of 
the system, display and print files, and set and change passwords. It includes 
information for intermediate to advanced users about how to use communi- 
cation and networking facilities and write shell procedures. 
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Chapter 1. Introduction 


CONTENTS 
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About This Chapter 
This chapter includes the main features of the AIX C language and a summary of 
terms and concepts in this manual. 
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Overview 


IBM AIX C Language provides a high-performance optimizing compiler that 
produces object code for execution under the AIX Operating System. 


IBM AIX C offers these functions: 


Automated installation 

Optimized executable code 

Excellent compile-time performance 

Separate module compilation 

Access to command-line options 

Easy inter-language linkages among VS Pascal, VS FORTRAN, and C. 


Throughout this manual, whenever possible, common elements between AIX PS/2, 
RT PC AIX, and AIX/370 have been grouped together. 


The main topics covered in this manual are: 


The Compiler 


C-Language source code is compiled on AIX by executing the ec command. It 
produces executable binary code from the C source code. 


C-language source code can also be compiled on the PS/2 by executing the vs 
command. The vs command 1s a script that is user modifiable. 


Data Representation 


This manual describes characteristics of the C data types as defined by the C 
Compiler in AIX. It also describes how the C Compiler represents data in 
storage. 


Mixing Languages and Linkage Conventions 


The PS/2 and RT PC language systems permit the mixing of elements from dif- 
ferent languages in a single program. The IBM AIX/370 language system 


permits mixing elements of the C and Assembler languages in a single program. 


You should be familiar with the languages you want to mix; the elements of the 
languages are not described here in detail. 


This manual also describes how to organize System/370 specific run-time func- 
tions and how the compiler meets register usage conventions. 


In this manual, the FORTRAN language described is IBM VS FORTRAN; the 
Pascal language is IBM VS Pascal; and the C language is IBM C. 
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Chapter 2. The Compiler 


CONTENTS 


About This Chapter 
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This chapter contains instructions for compiling C programs and describes each of 
the command-line options. Optimization capabilities are also described in detail. 


The Compiler 


C-Language source code 1s compiled on AIX by executing the cc command. See the 
AIX Operating System Commands Reference. It produces executable binary code . 
from the C source code. 


Note: C-language source code can also be compiled on the PS/2 by executing the vs 
command. The vs command is a script that is user modifiable. See the ALY Oper- 
ating System Commands Reference. 


Invoking the Compiler 


To run the compiler from the command line, enter the following: 
cc [file| [ option] ... 


where file is any one of the file types described later under “File Types” and option is 
any one of the options described under “Command-Line Options.” 


Description 


The ce command runs the C compiler. It accepts files containing C source code, 
assembler source code, or object code and changes them into a form that the 
compute system can run. The ec command compiles and assembles source files 
and then links them with an specified object files, in order listed on the 
command line. It puts the resulting executable program in a file named a.out. 
Command-line options are used to modify this process. 


The Configuration File 


The configuration file, /ete/ec.cfg, holds definitions for standard path names of 
compiler components, header files, and libraries; standard preprocessor macro 
definitions; and default values of other options. These definitions may be over- 
ridden by the -B, -I, -L, -D, and -U flags. An alternative configuration file may 
be designated by the -F flag. See ALY Operating System Technical Reference for 
a discussion of cc.cfg. 


Standard macro definitions include AIX family plus one of _ATX370, AIXPS2 
or AIXRT to identify the AIX platform, plus STDC_ if compilation is at the 
Standard C language level. | 


File Types 
The ee command recognizes and accepts the following file types. 


file.c A C language source file. A .c file is preprocessed, compiled, and assem- 
bled to produce an object file named file.o. When a single file is com- 
piled and linked in one command, the .o file is not preserved. The -e flag 
suppresses linking and produces a .o file. Compiling multiple files with 
or without linking always produces .o files. 


file.i Treated like a .c file, except that the preprocessing step is skipped. 


file.s An assembly language source file. A .s file is treated like a .c file, except 
that preprocessing and compiling steps are skipped. 


file.o An object file. A .o file is passed to the linker. 
file.a A library (or “archive’’) file. A .a file is passed to the linker. 
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-lkey An abbreviation for the library file name libkey.a -lkey is passed to the 
linker, which searches for libkey.a in directories designated by -L flags, 
then in standard directories. 


other A file name without a single-letter suffix 1s passed to the linker. 


Command-Line Options 


Command-line options may or may not be common across platforms. See the indi- 
vidual options for any notes or exceptions. 


The following command-line options are also described with the ce command in ALY 
Operating System Commands Reference. 


The ec command recognizes several flags. In addition, flags intended to modify the 
action of the linkage editor (Id), the assembler (as), or the preprocessor (cpp) may 
also appear on the ce command line. ce sends any flags it does not recognize to 
these commands for processing. The following list includes the most commonly used 
cpp flags (-D, -I, and ld flags (-l, -L , -o). 


-a 


=¢ 


-Dname[ = def] 


-E 


-f2 


“8 


-G 


Reserves a register for extended addressing. You should use this 
flag if a compiled procedure creates a stack greater than 32,767 
bytes. Because this flag causes the compiler to reserve a register 
for use by the assembler, it reduces the number of available regis- 
ters by one. 


Note: This option is not supported on the PS/2 or System/370. 


Does not send the completed object file to the ld command. 
With this flag, the output of ce is a .o file for each .e or .s file. 


Defines name as in a #define directive. If no equal sign is speci- 
fied, the default defis 1. If an equal sign but no def is specified, 
the def is null. This can be used to remove occurrences of name 
from a file. 


Runs the named C source file through only the preprocessor and 
writes the result to standard output. 


Generates code that uses the Floating-Point Accelerator or 
Advanced Floating-Point Accelerator. Programs compiled with 
this flag will run correctly only on 032 microprocessors config- 
ured with either of the Floating-Point Accelerators. 


Note: This option is not supported on the PS/2 or System/370. 


Generates code that uses the Advanced Floating-Point Acceler- 
ator. Programs compiled with this flag will run correctly only on 
AIX processors configured with the Advanced Floating-Point 
Accelerator and an Advanced Processor Card. 


Note: This option is not supported on the PS/2 or System/370. 


Produces additional information for use with a symbolic 
debugger (for example, the dbx command). 


Indicates that global variables are volatile. The optimizer makes 
fewer transformations when you specify this flag. To make a 
particular variable volatile, add the .volatile specification to its 
declaration. 


Note: This option is not supported on the System/370. 
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-Idir 


-lkey 


-Ldir 


-N[ndpt |num 


-oname 


-O 
“p 


-P 
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Treats files with the suffix .h in the same way as files with the 
suffix .c. 


Note: This option is not supported on the System/370. 


Looks first in the directory specified by dir, then looks in the 
directories on the standard list for #include files with names that 
do not begin with / (slash). 


Searches the specified library file, where key selects the file 
libkey.a. Id searches for this file in the directory specified by an -L 
flag, then in /lib and /usr/lib. The ld command searches library 
files in the order in which you list them on the command line. 


Note: If you use the -I flag, it must be the last entry on the 
command line, following any file parameters. 


Looks in the directory specified by dir for files specified by -1 
keys. If it does not find the file in the directory specified by dir, 
Id searches the standard directories. 


Changes the size of the symbol table (n), the dimension table (@), 
the constant pool (p), or the space for building the parse tree (t). 
Each table must be changed separately. The default size of the 
symbol table is 1500; the default size of the dimension table is 
2000; the default size for the constant pool is 600; the default 
space for the parse tree 1s 1000. 


Note: This option is not supported on the PS/2 or System/370. 


Assigns the file name specified by name rather than a.out to the 
output file. 


Note: On the PS/2, if a debug/disassembler file (.d) exists and 
the output file specified is in a directory other than the current 
directory, the .d files are moved to the output file directory. 


Sends compiler output to the code optimizers. 


Prepares the program so that the prof command can generate an 
execution profile. The compiler produces code that counts the 
number of times each routine 1s called. If programs are sent to 
Id, the compiler replaces the startup routine with one that calls 
the monitor subroutine at the start (see AIX Operating System 
Technical Reference for a description of this subroutine), and 
writes a mon.out file on normal program termination. 


Like -p, but invokes a run-time recording mechanism that keeps 
more extensive statistics and produces a gmon.out file at normal 
termination. You can then use gprof to generate an execution 
profile. 


Runs the named C source file through only the preprocessor and 
stores the output in a .i file. 


Note: The -P option is not supported on the System/370. See 
the -E option for equivalent results. 


-R 


-S 


“WwW 


-X 


-Uname 


-y[| dmnpz | 


Turns off inlining. The following may be used: 


? Shows the reason for not inlining in the 
output file. 


-name,name... Does not inline name. 
+name,name... Inlines name. 
lnum Limits the size increase of the function in 


which inlining occurs to num intermediate 
operations. The default num is 100. 


#num Limits the expansion of an individual call to 
num intermediate operators. The default num 
is 100. 

-@file Reads a list of forbidden functions from file. 

+ @file Reads a list of requested functions from file. 


Requesting a function to be inlined overrides size constraints. 


Note: The PS/2 C Compiler only accepts the -Q! syntax. In this 
case, all inlining 1s disabled. 


Compiles initialized data into the text segment, making the data 
read-only. 


Compiles the specified C programs, storing assembly language 
output in a. s file. 


Prevents printing of warning messages. 


Note: The RT PC C Compiler prevents printing of warning mes- 
sages about functions that cannot be optimized. 


Produces an assembier listing. This is stored in a file that has the 
same name as the assembler source file but with the extension .Ist 
instead of .s. 


Note: On the PS/2, the assembler code listing may not match the 
executable code generated by the C Compiler. This is because 
the C Compiler directly generates machine code; there is no sepa- 
rate assembler pass. This is not supported on the System/370. 


Undefines name as in an #undef directive. 


Specifies the rounding mode for floating-point constant folding. 
These modes are specified as follows: 


d Disables floating-point constant folding. 
m Rounds toward negative infinity. 
n Rounds to nearest whole number. This is the default 


action and applies to constant folding in all applicable 
passes of the compiler. 

Pp Rounds toward positive infinity. 

z Rounds toward 0. 


Note: This option is not supported on the PS/2 or the 
System /370. 
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-Z 
Debugging 

-V 

-# 
Extended Functions 

-Bprefix 
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Uses the libm.a version, or a verston specified by the user, of the - 
following transcendental functions: 


acos asin atan atan2 cos exp 


log logl0 ~— sin sqrt tan 





If this flag is not used, the compiler generates inline instructions 
for the 80387 math co-processor for the PS/2, or the Advanced 
Floating Point Accelerator for the RT PC. (For more informa- 
tion on libm.a, see math.h in the ALX Operating System Technical 
Reference.) 


Note: This is not supported on the System/370. 


Displays the trace as with -# and invokes the programs. 


Displays a trace of the actions to be taken (for example, invoking 
the preprocessor), without actually invoking any programs. 


Constructs path names for substitute preprocessor, compiler or 
optimizer programs. prefix defines part of a path name to the 
new programs. To form the complete path name for each new 
program, ec adds prefix to the standard program names (see ALX 
Commands Reference for a list of the standard program names). 


Note: The PS/2 C Compiler does not have a separate optimizer 
program. It also does not invoke the assembler as an interme- 
diate step to compiling a C program. 


For example, if you enter the command: 
cc testfile.c -B/usr/jim/new 
ee calls the following compiler programs on the PS/2: 


/usr/jim/newcpp 
/usr /jim/newvsc 
/usr/jim/newvspass2 
/usr/jim/newvspass3 


ec calls the following compiler programs on the RT PC: 


/usr/jim/newcpp 
/usr/jim/newccom0 
/usr/jim/newccecom1] 


ce calls the followimg compiler programs on the System/370: 


/usr/jim/newcpp 
/usr/jim/newhclcom 
/usr/jim/newhc2com 
/usr/jim/newas 
/usr/jim/newld 


Similarly, if you enter the command: 


cc testfile.c -B/usr/jim/new/ 


-t[ pegfal | 


ce calls the following compiler programs on the PS/2: 


/usr/jim/new/cpp 
/usr/jim/new/vsc 
/usr/jim/new/vspass2 
/usr/jim/new/vspass3 


cc calls the following compiler programs on the RT PC: 


/usr/jim/new/cpp 
/usr/jim/new/ccom 
/usr/jim/new/ccom1 


ec calls the following compiler programs on the System/370: 


/usr/jim/new/cpp 
/usr/jim/new/hclcom 
/usr/jim/new/hc2com 
/usr/jim/new/as 
/usr/jim/new/Id 


The default prefix is /lib/o. 


Applies the -B flag instructions for constructing file names to 
only the designated programs. 


The parameters accepted on the PS/2 are: 


preprocessor 
compiler first 
compiler second 
compiler third 
assembler 
linkage editor 


m— ep “=I O'S 


The parameters accepted on the RT PC are: 


P —_si—preprocessor 

c compiler first 

q intermediate code optimizer 
2 compiler second 

0 optimizer 

a assembler 

| 


linkage editor 
The parameters accepted on the System/370 are: 


pass 1 and 2 of the compiler 
preprocessor 

loader 

pass | of the compiler 

pass 2 of the compiler 
assembler 


Ss Nes = S OO 


The -t flag with no additional parameters designates by default 
the preprocessor and compiler programs. 


If you do not specify the -B flag when you specify the -t flag, the 
default file name prefix is /lib/n. 
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Notes: 


1. You can specify this prefix with the -B flag. However, 
depending on what combination of the -B and the -t flags 
you specify, prefix can have two possible default values. If 
you specify -B but no accompanying prefix, the default prefix 
is /lib/o. If you specify the -t flag without also Specsly ins the 
-B flag, the default prefix is /lib/n. 


2. The System/370 does not supply default values for the -t or 
-B flag. 


-Wc.flagl{flag2... | 


PS/2 Specific Options 


Gives the listed flags to the compiler program specified by c; c 
can be any one of the values described with the -t flag. For 
example, since both Id and as recognize a -o flag, use -W to 
specify the program to which the flag is to be sent. For example, 
-W1,-o sends it to Id and -Wa,-o sends it to as. 


The AIX PS/2 C Compiler specific options are described below. They indicate which 
features are enabled or disabled when the compiler is invoked. The options are 
described in alphabetical order. 


b+ 


d+ 


efilename 


g+ 
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Floating Point Computation 


Instructs the compiler to promote all floating-point values to double 
precision before all floating-point computations. 


Disassembler Information 


Produces additional information for use with the dis command (the 
disassembler). 


Note: With this option, you can also use the dbx command (sym- 
bolic debugger). (See the g+ option below.) However, the .d file 
does not contain symbolic information; therefore, you can only do 
machine level debugging. 


Error File 


Instructs the compiler to place its error output in the file specified 
by filename. If the efilename option is not specified, error messages 
are written to the standard error device. 


Debugger Information 


Produces additional information for use with the dbx command (the 
symbolic debugger). 


Notes: 


1. With this option, you can also use the dis command (disassem- 
bler), see the d+ option above. However, allocation of vari- 
ables into registers is turned off. 


2. If both the d+ and the g+ command-line options are set, 
regardless of their order on the command line, the g+ option 
has the higher priority. 


3. The optimization process is disabled whenever the g+ option is 
specified on the command line. 


Ifilename 


I+ 


ol+ 


o2+ 


03+ 


04+ 


V+ 


System/370 Specific Options 


Listing File 
Instructs the compiler to place its listing output in the file specified 


by filename. If the lfilename option is not specified, a listing file is 
not generated. 


List to Standard Output Device 


Instructs the compiler to generate a listing to the standard output 
device. 


Optimization Level 1 


Instructs the compiler to use optimization level 1 (see “Optimization 
of Programs” on page 2-16). 


Optimization Level 2 


Instructs the compiler to use optimization level 2 (see “Optimization 
of Programs” on page 2-16). 


Optimization Level 3 


Instructs the compiler to use optimization level 3 (see “Optimization 
of Programs” on page 2-16). 


Optimization Level 4 


Instructs the compiler to use optimization level 4 (see “Optimization 
of Programs” on page 2-16). 


Compiler Progress Information 


Instructs the compiler to generate information on the progress of the 
compile. 


No Warning Messages 


Instructs the compiler not to generate warning messages. 


The AIX/370 compiler options are described below. 


-F file[:stanza] Uses an alternate file and/or stanza for the ce configuration. See 


-Hanno 


-Hansi 


-~Hasm 


AIX Operating System Technical Reference for discussions of the 
configuration file /etc/cc.cfg. 


Used in conjunction with the -S option (explained below). Specifies 
that the generated -S file is to be annotated with lines from the 
source file. 


Causes the compiler to accept only programs conforming to the 
ANSI Standard. 


Directs the compiler to produce a (pseudo-) assembly listing of the 
generated code on standard output, by initializing the Asm toggle to 
On. The assembly listing is annotated with lines from the main 
source file, but not with lines from any included files. These lines 
appear as comments immediately preceding the corresponding 
assembly instructions. If the -S option (described below) is also 
specified, the generated .s file is annotated with lines from the 
source file, and no listing is written on standard output; that 1s, it 
has the same effect as -Hanno. 
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-Hepp 


-Hnocpp 
-Hfsingle 


-Hlines = n 


-Hlist 
-Hxa 


-M 


-Hon = toggle 
-Hoff = toggle 
-Hpcc 


-H+w 
-M 
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Specifies that the outboard C macro preprocessor (/lib/cpp) is to be 
used, rather than the inboard preprocessor. 


Specifies the use of the inboard C macro preprocessor. 


Specifies that single-precision arithmetic is to be used in computa- 
tions involving only float expressions. That is, floating-point oper- 
ations are not to be performed in double precision, which is the 
default. Note that non-prototyped functions declared to return float 
may actually return double, depending on the setting of the toggle 
Double_return. Some programs run much faster with this option, 
but beware of loss of significance due to lower-precision interme- 
diate computations. 


Causes a page eject to occur after every n lines written to standard 
output. The default of 60 is appropriate for most 6-lines-per-inch 
printers, which allow a maximum of 66 lines per page for 11-inch 
paper. The setting of -Hlines is intended to allow some blank space 
at page boundaries. For 8-lines-per-inch (88 lines per page) printers, 
-Hlines should be set to 80 or 82. This option is used in conjunction 
with the -Hlist and -Hasm options. If n is 0, no page ejects are 
emitted. 


Causes the compiler to generate a source listing on standard output. 
It works by initializing the List toggle to On. 


Generates an XA370 executable. 


Specifies that the outboard C macro preprocessor is to be invoked 
and makefile dependencies are to be generated. The output is sent 
to standard output. No compilation occurs. 


Turns a toggle On. 
Turns a toggle Off. 


Specifies that the compiler is to run in PCC mode. In this mode, 
the compiler relaxes enough of the ANSI extensions to more or less 
emulate the Portable C Compiler. This permits old C programs that 
would not ordinarily compile to compile with little (if any) modifica- 
tion. 


Specifically, -Hpee does the following: 
Turns on the PCC toggle 
Unreserves the following keywords: signed, volatile, and const. 


Turns on the Long_enums toggle so that enum types are mapped 
to full words as is the PCC convention. 


Issues all warnings by turning off the PCC_msgs toggle. 


Generates makefile dependencies for the named C files and writes 
the result to standard output. Does not compile or link. 


Compiler Toggles (AIX/370) 


The AIX/370 C Compiler provides a set of toggles, which can be initialized on the 
command line, with -Hon and -Hoff. See “Invoking the Compiler” on page 2-2. 


The names, default values, and meanings of the compiler toggles are described below. 
Many of the defaults can be altered by making appropriate changes in the /ete/cc.cfg 
file. Toggles with alterable defaults are denoted by the presence of alterable in the 
descriptions below. 


Align_members — Default: On 


Asm — Default: Off 


When On, members of structures are aligned. When Off, no such alignment takes 
place. Not all other implementations of AIX C permit member alignment to be sup- 
pressed. 


When On, a (pseudo-)assembly listing is generated, annotated with source code as 
assembly comments. If the Asm toggle is to be turned On and Off over sections of a 
module, On-Off pairs should surround function definitions; if the pragma is used 
among executable statements, the point at which the pragma takes place may be 
obscured by the use of optimizations. 


Char_default_unsigned — Default: On 


When On, type char is unsigned by default. 


The Standard allows the type char by itself, that is, without the adjectives unsigned 
or signed, to be either signed or unsigned. Of course, the types unsigned char and 
signed char can be used to explicitly control signedness. 


Char_is_rep — Default: Off 


The ANSI Standard provides three character data types: char, unsigned char, and 
signed char. Even though char is signed or unsigned, depending on the implementa- 
tion, it is never the same type as signed char or unsigned char. One of the effects is 
that char* is type compatible with neither unsigned char* nor signed char*. This 
increases program portability. 


When On, Char_is_rep specifies that char is identically either signed char or unsigned 
char, depending on whether char is signed or not. Although this may permit a 
program to compile, the program might not compile under another C implementa- 
tion where the signedness of char is different. Be sure to turn this toggle On before 
any declarations or preprocessor statements. 


Cross _jump—Default: On 


When Off suppresses the cross-jumping (tail-merging) optimization that is otherwise 
performed when -o is specified. Suppressing cross-jumping can make code easier to 
debug at the instruction level. 
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Double_math_only — Default: On 


When On, floating-point operations are performed in double precision. 


When two operands of certain arithmetic operations are both of type float, the 
Standard permits an implementation to do one of two things: perform the operation 
using float arithmetic, in which case the result of the operation is of type float, or 
convert both operands to type double and use double arithmetic, in which case the 
result of the operation is of type double. When toggle Double_math_only is turned 
Off, the first option is used. When it is turned On, the second is used instead. 


Double_return — Default: Off 


When On, any non-prototype function returning type float returns type double 
instead. This convention conforms to some Portable C Compiler implementations. 


Downshift_file names — Default: Off 


When On, the file name specification of any subsequent Include pragma is inter- 
preted as if it were in all lowercase. This toggle is useful when moving source code 
from an operating system in which file-name casing is not significant to a system in 
which it is significant. 


Int_function_warnings — Default: Off 


List — Default: Off 


When Off, suppresses the warning message normally generated when a function 
returning int has no return exprn statement within it, or when a function returning 
int contains a return within it. 


This is to remove frequent warnings for old C source that did not use the reserved 
word void to indicate a function returning no result, because such functions return 
int by default. 


When On, the compiler produces a listing on standard output. It is typically given 
when starting the compilation but may appear in the source file to turn the listing 
On or Off around a particular section of source. 


Long_enums — Default: Off 


When On, any variable of an enum type is mapped to a full word. Otherwise, such a 
variable is mapped to the smallest of one, two, or four bytes, such that all values are 
representable. 


Make_externs_global — Default: On 


When On, any local declaration of an object with storage class extern is made global 
if there is not already a global declaration of the object. Early C compilers pro- 
moted an extern declaration within a function to the global scope. This toggle sup- 
ports programs depending upon that feature. 
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Parm_warnings — Default: On 


PCC — Default: On 


When On, the compiler produces warnings whenever arguments to a non-prototype 
(old-style) function F do not match the types of the declared formal parameters of F. 
Frequently this inconsistency is a source of disastrous or difficult-to-find bugs. 
Example: 


double square(x) double x; {return x*x;} 


printf("%d\n",square(3)); 


In this example, square is passed the integer 3, not double-precision 3.0, and the 
compiler issues a warning. The C language definition prohibits the compiler from 
casting 3 to a double before passing it. 


To eliminate the compiler warnings, turn Off the toggle Parm_warnings. 


We recommend, however, that the program text be repaired to eliminate the 
offending function calls rather than eliminating the potentially useful feedback from 
the compiler. 


There are many UNIX C programs that compile under the Portable C Compiler that 
will not compile under an ANSI compiler such as the C compiler. When the PCC 
toggle is turned On, many of the ANSI restrictions are relaxed so that such pro- 
grams are more likely to compile (with appropriate warnings). 

The following is a list of the ANSI restrictions that this toggle affects: 


Structure member selection is permitted on a variable of any type; it need not be 
a struct or union. However, if the name of the member being selected is declared 
as a member in more than one struct or union definition, each occurrence must 
be declared with the same type and be mapped at the same offset. 


Any pointer type is considered compatible with any other pointer type. 
Note: Turning On the toggle Pointers_compatible has this effect. 
Pointers and any integer type are considered compatible. 


Note: Turning On the toggle Pointers_compatible_with ints has this effect. 


These PCC language features are not supported: 
e (Cast) variable as left side of assignment 
e Old-fashioned assignment operators (= +) 
e Old-fashioned initialization (no =) 
e Unsignedness-preserving semantics. 


See also the -Hpce compiler option in the section “Invoking the Compiler” on 
page 2-2. 


PCC msgs — Default: Off 


When On, the diagnostic capabilities of the compiler are reduced to the PCC (“Port- 
able € Compiler”) level, in that the following warnings are not emitted: 


Function called but not defined. 
"=""used where "==" may have been intended. 
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In addition, this toggle disables warnings about passing an int, for example, to a 
non-prototyped function expecting a long int, because int and long int are the same 
size. 


When all warnings are enabled in C, code must be “squeaky clean” to get through 
the compiler without a warning. Some users have code that was designed with a 
compiler that is not so demanding, and would prefer fewer prods from the compiler. 
Hence the PCC_msgs toggle is supplied. 


Note: The -H+w command-line option turns this toggle Off. 


Pointers_compatible — Default: Off 
When On, the compiler permits a pointer value to be assigned to an incompatible 
pointer variable, with an appropriate warning. 


Pointers compatible with_ints — Default: Off 
When On, allows pointers of any type to be compatible with ints, with an appro- 
priate warning. Although this is in violation of Standard and C compiler specifica- 
tions, many old C programs improperly assign pointers to ints and vice versa. This 
toggle allows such programs to be compiled without modification. 


ANSI and the C compiler disallow this dangerous practice because pointers are not 
necessarily the same size as ints on all machines. 


Print_ppo — Default: Off 
When On, the output of the preprocessor is written to standard output. With this 
toggle, it is possible to print what the compiler proper receives over a local area of 
source code. This toggle can be used to inspect the expansion of a macro, by 
turning the toggle On prior to the macro invocation and Off after it. 


Note: This toggle is ignored unless -Hnocpp is specified or is the default. 


Print_protos — Default: Off 
When On, the compiler writes to standard output a new, prototype-style function 
header for each function definition. This toggle aids in the conversion of C pro- 
grams to the ANSI prototype syntax derived from the C language. For example, for 
the function definition: 


int f(x,y,z) int *x,z[]; double (*y)(); {...} 
the compiler produces the following output: 
int f(int *x, double (*y)(), int [z]); 


The old function header can then be replaced with the generated one. 


Prototype _conversion_warn — Default: On 
When On, the compiler generates a warning message when a function’s argument is 
converted due to a prototype declaration. 


When using function prototypes, the compiler may automatically convert a func- 
tion’s argument so that the argument’s type matches that of the formal parameter. 
Wherever such a conversion does not match what would happen in the absence of 
prototypes, such C code would probably not run correctly on older C compilers that 
lack prototypes. 
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Prototype override warnings — Default: On 
When On, the compiler produces a warning whenever a declaration (not definition) 
for a function using the new prototype syntax overrides the semantics of an old-style 
function definition. 


Standard C requires that function prototype declarations override old-style function 
definitions. This means that the simple inclusion of a .h header file with prototype 
declarations of functions will obtain the new prototype semantics for the definitions 
of those functions. This feature has both disadvantages and advantages. 


The advantage is that the new prototype semantics — the Pascal-style assignment- 
conversion of arguments to the types of the formal parameters — 1s obtainable by 
merely including a declaration in a header file. The disadvantage is that a definition 
can no longer be read out of context; without searching header files one cannot 
determine whether or not the compiler compiles the function using prototype-style 
semantics. 


For example: 


file header.h: 
int func(float f,long 1); 


file prog.c: 
#include "header.h" 
int func(f,1) float f; long 1; { 


void sub() { 
func(3, 4.4); /* Passes 3.0 and 4L via */ 
} /* automatic conversion. */ 


Were header.h not included, the call to func in sub would pass the int 3 and the 
double 4.4, and probably func would not work properly. With the header file 
included, the interface for func is changed to prototype-style (3 is converted to float 
and 4.4 to long). Thus, one can find out how the compiler treats func only by 
searching all the header files. 


To obviate the need for searching, AIX C provides a warning message whenever an 
old-style definition is overridden by a prototype. The warning message can be disa- 
bled by turning Off toggle Prototype_override_warnings. 


We recommend that function definitions be written with the new prototype syntax 
for improved readability and reliability. 


For example: 


file prog.c: 
int func(float f,long 1) { 


The ANSI committee permitted the override feature for two reasons: first, it would 
take some work to convert programs to use the new syntax in the definition 
(although with toggle Print_protos, AIX C generates the headers from old-style defi- 
nitions); second, most compilers do not support prototype-form definitions, and the 
use of a header that is conditionally included based upon the compiler being used 
makes code more easily compilable by different compilers. 


Chapter 2. The Compiler 2-15 


Read only strings — Default: Off 
| ~ When On, string constants are placed in a read-only data section. Two or more 
identical string literals in the same module will appear only once in memory. It is an 
error to modify the storage of a string constant at run time when the toggle is On. 


C string literals are not true literals because they are writable data items. This 
means that they cannot normally be placed in code space. Furthermore, two iden- 
tical C string literals must normally be duplicated in a program’s object code, 
because one might be modified and the other not. To avoid this, use 
Read_only_strings and Literals_in_ code. These two toggles cause C string literals to 
be placed in code. 


Recognize library — Default: On 
When On, the compiler may substitute in-line code for any function defined in the 
ANSI Standard C library. Candidates for substitution currently include the math 
and string functions. Future releases may encompass more of the library. 


Warn — Default: On 
When Off, warning messages are suppressed. The -w command-line option turns 
Warn Off initially. 


Optimization of Programs 


Optimization refers to the process of improving the execution performance of a given 
program. It is done at the cost of compile time but results in reduced execution 
time. The AIX C Compiler performs two separate optimization passes—machine- 
dependent optimizations and machine-independent optimizations. 


On the PS/2, the type of optimizations are controlled by selecting compiler 
command-line options. The command-line options for optimization are: 


ol+ Machine-dependent Optimization 


Instructs the compiler to perform a machine-dependent optimizing pass, 
which takes place after the code-generation phase of the compilation. This 
pass examines object code at the basic block level and includes: 


e Eliminating unnecessary branches 

e Eliminating redundant loads and stores 
e Exploiting machine idioms 

e Strength reduction. 


02+ Machine-independent Optimization 


Instructs the compiler to perform a machine-independent optimizing pass that 
includes: 


e Constant folding 

e Straightening 

e Eliminating unreachable code 
¢ Copy propagation 

e Eliminating dead code. 
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03+ Machine-independent Optimization 


Instructs the compiler to perform a machine-independent optimizing pass that 
includes: 


¢ Eliminating common subexpressions 
¢ Subscript optimization 

¢ Eliminating induction variables 

¢ Loop invariant code motion. 


04+ Machine-dependent and Machine-independent Optimization 


Instructs the compiler to perform machine-dependent and machine- 
independent optimization. 


On the RT PC, both machine-dependent optimization and machine-independent 
optimizations are invoked by selecting the -O flag. 


The machine-dependent optimizations are: 


e Elimination of unnecessary branches 

¢ Elimination of redundant loads and stores 

e Strength reduction 

e Replacement of branches with branch-with-execute instructions 
e Instruction scheduling. 


The machine-independent optimizations are: 


e Constant propagation and folding 
¢ Code motion of loop invariants 

e Unused variable elimination 

e Dead code elimination 

¢ Idiom recognition 

¢ Common subexpression elimination 
°* Register allocation 

e Value recognition 

¢ Copy propagation 

e Short circuiting 

e Integrated return/assignment. 


Optimization Considerations (AIX/370) 
The choice of algorithm for a given task can have a much greater impact on exe- 
cution speed than any compiler optimization. It is generally true that most of 
program execution time is spent on less than 10% of the code. Changes to the algo- 
rithm in the critical 10% frequently have dramatic results. 


The optimizing feature of the compiler should not be used while developing pro- 
grams. Some optimizations move statements from one area of a program to 
another, or change statements or variables in a way that is not obvious. Since this 
makes debugging programs more difficult, optimizing before debugging should be 
avoided. After a program is developed, it can be recompiled with optimization 
command-line options to improve its performance. 


The compiler translates each function definition into an internal representation that 
materializes every computation required by the target machine, down to the loading 
and storing of registers. The internal representation assumes the existence of an 
unlimited number of virtual registers. The register allocation phase maps these 
virtual registers into the set of machine registers. 
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The internal representation is maintained in the form of a flow graph on which a 
series of optimizations is performed. Each node of the graph represents a block of 
code that has no more than one entry point or exit point. The following is a brief 
description of the optimizations, on the 370, in roughly the order they are per- 
formed: 


e¢ Dead Code Elimination 


The compiler eliminates any block of code that has no predecessor block (that is, 
there exists no path to the block). This phase is invoked from other phases 
when it is potentially valuable to do so. For example, constant propagation may 
convert a conditional jump into an unconditional jump and thus eliminate a 
path out of the associated block. 


¢ Constant Propagation 


When the compiler sees a variable being referenced such that the last value V 
assigned to that variable was a constant, the reference is replaced with V. For 
example: 


int debug; 
debug = 0; 
vf Caenugy /* Constant propagation back-substitutes 0. */ 
e Constant Expression Folding 
Arithmetic expressions whose operands are constants are evaluated at compile 


time. Constant propagation often exposes such expressions that are not other- 
wise apparent. 


¢ Local Common Subexpression Elimination (Local CSE) 


The compiler divides the flow graph into a minimum number of sub-graphs such 
that each sub-graph is a tree (that is, each node not having more than one pred- 
ecessor but any number of successors). Common subexpressions are eliminated 
across nodes of each sub-graph through a technique known as value numbering. 
It recognizes the commutativity of operations so that “A+B” yields the same 
value as “B+A.” It also keeps track of copy propagation so that, in the fol- 
lowing example, the expressions a+b and c+d would be recognized as redun- 
dant: 


int a,b.c,d,e,f; 


e = atb; 
d = a; 
c=); 


f 


| 


ctd; /* <== Same value as atb above. */ 
¢ Global Common Subexpression Elimination 


In this phase, common subexpressions are eliminated across the entire flow 
graph. Unlike the local CSE phase, the analysis is restricted to arithmetic identi- 
ties. 


¢ Invariant Expression Removal from Loops 


Any register computation that is invariant within a loop is moved above the 
loop. 
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Live/Dead Analysis 


Computations whose results are never used are eliminated. Dead stores are also 
eliminated. 


Strength Reductions 


Multiplication by a constant is converted to a series of additions, subtractions, 
and shifts. Division and modulo by a integer power of two are converted to a 
shift or masking operation. 


Global Register Allocation 


Register allocation is performed by building an interference graph and coloring 
it. Each node of the interference graph represents a virtual register. Each edge 
of the graph designates two registers that are alive at the same time and there- 
fore must be mapped to different machine registers. The coloring process 
assigns each node to a machine register such that no two adjacent nodes are 
mapped to the same register. 


Some ANSI-Required Specifics (AIX/370) 
ANSI document X3J11/88-090 requests that each C implementation provide the fol- 
lowing system specifics. 


Identifiers 


There is no imposed limit on the number of significant characters in an identi- 
fier. Casing 1s preserved. 


Characters 


Source and execution character sets are both Standard ASCII. Each character 
in the source character set maps into the identical character in the execution 
character set. Without exception, all character constants map into some value in 
the execution character set. 


A character is stored in a byte, and there are four bytes in an int. 


The type specifier char, when not accompanied by an adjective, denotes an 
unsigned character type. However, this can be changed by turning Off the 
toggle Char_default_unsigned. 


Integers 


Integers are represented in two’s-complement binary form. The following table 
illustrates the ranges of values to which the various integer types are restricted: 


signed char 127 
unsigned char 2a 
short -32,768 32,767 
unsigned short 0) 65,535 


int -2,147,483,648 2,147,483,647 
unsigned int 0 4,.294,967,296 
long -2,147,483,648 2,147,483,647 
unsigned long 0 4,294,967,296 





An integer is converted to a shorter signed integer or int bit field by bit trun- 
cation; that is, when an X-bit value is to be stored into a Y-bit receptacle, where 
X > Y, the rightmost Y bits of the first value are stored. 
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An unsigned integer U is converted to a signed integer I where sizeof (U) = 
sizeof(I) by transferring the bits of U into I, whether or not the value of U is 
representable in I. For example, (short int)(short unsigned) 65535 is the short int 
value -1. The sizeof operator returns an int, unless the value returned is not 
representable in int, in which case unsigned int is the type returned. 


The result of a bitwise operation on a signed integer is the same as if the integer 
were treated as unsigned. 


The sign of the remainder on integer division is the same as the sign of the divi- 
dend. 


The right shift of a signed integral type is arithmetic; that is, the sign bit is prop- 
agated to the right. 


Floating point 


Floating-point data is represented in the floating-point format defined in JBM 
System 370 Principles of Operation manual. The default rounding mode is to 
“truncate toward zero.” 


When a negative floating-point number is truncated to an integral type, the trun- 
cation is toward zero. Thus -2.7 is truncated to -2 and -1.2 to -1. 


Pointers 
The difference of two pointers is type int. 
Registers 


The compiler attempts to map each auto- (or register-) class variable to a register 
provided that its type is appropriate and its address is not required. 


Structures, unions, and bit fields 


Signed and unsigned bit fields are supported. A bit field declared as int is 
treated as unsigned int. A bit field declared as signed int will be interpreted as 
signed. 


Preprocessing directives 


A single-character constant in a constant expression controlling conditional 
inclusion is always non-negative in value, ranging from 0 to 255. 


Floating-Point Exceptions for AIX PS/2 


The following six operations or types of operations can produce an AIX floating- 
point exception. They apply to PS/2s configured with or without the Intel 80387 
floating-point coprocessor. 


Stack operations—stack overflow, underflow 

Arithmetic operations—includes invalid operations defined in IEEE Standard 754 
Division by zero 

Denormal number 

Overflow 


Underflow. 


Floating point exception interrupts are disabled by default. You can use the 
fp_control, fp_exmask, fp_exunmask, fp_round, fp_precision, fp_getex, fp_getprecision, 
fp_getcw, fp_restore, and fp_getround subroutines to manipulate the runtime environ- 


2-20 C Language User’s Guide 


ment with respect to floating-point handling and to set the desired rounding and pre- 
cision modes. (See ALY Operating System Technical Reference for more information 
about these subroutines.) 


The following is an example of a program that writes the current control word and 
then enables the divide by zero interrupt. Note the inclusion of the header file 
/usr/include/sys/fpcontrol.h, which defines the constant FPM_ DIVIDE _0. Also, see 
fp_getcew(3) for the library calling option. 


#include <sys/fpcontrol .h> 
main () 


double x,y; 
printf ("%d\n",fp_getcw()); 
fp_exunmask(FPM DIVIDE_@); 


x = 0.0; 
y = 1.0; 
y = y/xs 


} 


Any combination of the exception mask constants defined in fpcontrol.h can be 
ORed together to form the desired argument to the appropriate subroutine. 


C Programs Under AIX 


As illustrated in Figure 2-1 on page 2-22, the four main steps in creating an execut- 
able C program under the AIX Operating System are: 


1. Create your program using a text editor and store it with a .c extension. 


2. Compile your source program to generate an object file. The compile process is 
described in detail below. 


3. Link the output with the AIX system linker Id to create an executable file. 

4. Run the program. 
Steps 2 and 3 are executed by the cc command, which includes the libe.a library by 
default. 


Note: The RT PC C Compiler also includes the librts.a library. Optional user 
libraries may be added to the ce command line by using the -I option flag. 
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STEP 1 


| a | 
Cc | 








STEP 2 
Source Compiler Binary File 
File 0 
Cc 
STEP 3 







Binary File 
-0 


Library AIX Executable File 
| /lib/libc.a ——>! Linker , a.out 









Id 





ser Library Files | 
(Optional) 


U 


STEP 4 


Run the 


program 





Figure 2-1. Creating a C Program Under AIX 


PS/2 and RT PC Compilation Process 


As illustrated in Figure 2-2 on page 2-23, the compiler follows these steps when 
invoked: 


1. The source file is passed to the epp command, the C preprocessor, which 
produces a preprocessed C source file. 


2. The preprocessed file is passed to vse, the C compiler front end, which produces 
intermediate code with an .i extension. 


3. The .i file is passed to vspass2, the code generator, which produces intermediate 
code with a .j extension. 
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4. The .j file is passed to vspass3, the code formatter, which produces a binary file 
with an .o extension. 


5. The .o file is passed to the AIX linker (Id) which creates an executable file. 


-c source file 


.i preprocessed file 





.1 file 


vspass2 


vsc 





vspass3 


t 


.o file | 


executable | 





Figure 2-2. PS/2 and RT PC Compilation Process 
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System/370 Compilation Process 
As illustrated in Figure 2-3, the compiler follows these steps when invoked: 


1. The source file is passed to the cpp command, the C preprocessor, which 
produces a preprocessed C source file. 


2. The preprocessed file is passed to hclcom and he2com, which produces assembler 
code. 


3. The assembler file is passed to as, the assembler, which produces a binary file 
with an .o extension. 


4. The .o file is passed to the AIX/370 linker (Id) which creates an executable file. 


Preprocessor 


source. file /\ib/cpp 


‘ 


compiler 


assembler 


binary file .o 


/Vib/libc.a 


user libraries 





executable 
file a.out 


Figure 2-3. 370 Compilation Process 


Note: The compiler consists of two passes: /lib/hclcom and /lib/hc2com. 
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This chapter describes how the AIX PS/2 C Compiler represents data in storage. It 
also describes characteristics of the C data types as defined by the C Compiler. 


Data Representations on PS/2 
The following terms are used as defined by the Intel 80386 microprocessor: 


e A byte contains 8 bits. 
¢ A word contains 16 bits. 
e A doubleword contains 32 bits. 


The following example shows the byte order of a word and doubleword stored in 


memory: 
15 7 0 
address nt n 
31 0 
over] | fowvone 
address nt+3 n+2 n+] n 


Although the 80386 microprocessor does not absolutely require alignment of data, 
there is a performance benefit in aligning 2-byte and 4-byte data. For this reason, 
the AIX PS/2 C Compiler seeks to align 2-byte entities on even addresses and 4-byte 
entities on addresses which are multiples of 4; 8-byte entities are aligned on addresses 
which are multiples of 4. 


Integral Representation 


The following information describes characteristics of the integral data types 
including the storage size in number of bits, the range of values represented by the 
data type, and the alignment. Two’s complement format is used for all signal integer 


types. 









signed char 


bit 


byte 0 


~~ 
ait 
© 


Sign 


char 0 to 255 
unsigned char 


bit / 0 


byte 0 









Alignment 
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= a 






short int 
signed short int 


bit 15 14 0 


| [byte 1 | byte 0 


Sign 









unsigned short 16 0 to 65535 word 
unsigned short int 


bit 15 0 


byte 1 | byte 0 








int -2147483648 to doubleword 

long 2147483647 | 
long int 

signed 

signed int 

signed long 

signed long int 


bit 31 30 0 


Tone [oe 






sign 


doubleword 









unsigned 0 to 4294967295 
unsigned int 
unsigned long 


unsigned long int 







bit 31 


He 
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Floating-Point Representation 


The following information describes characteristics of the floating-point data types. 
The AIX C Compiler supports both single and double precision floating-point data, 
according to the ANSI/TEEE 754-1985 standard. 


Single Precision 


float 32 Approximately doubleword 


-3.37e + 38 to 
3.37e + 38 





bit 31 30 23 22 Q 


Mantissa(23+1 bits) 





Sign 
Exponent,biased by 127 


The three fields of a single-precision floating-point number are: 


e A sign bit designated by sin the diagram. The sign bit is 1 only if the floating- 
point number is negative. 


e An 8-bit biased exponent. 
e A 23-bit mantissa with the high-order 1-bit hidden. 


Double Precision 


double Approximately doubleword 


long double -1.67e + 308 to 
bit 63 62 52: Oo! 0 


1.67e + 308 


sign 
















Mantissa 


Mantissa(52+1 bits) 
Exponent,biased by 1023 


The three fields of a double-precision floating-point number are: 


e A sign bit designated by sin the diagram. The sign bit is 1 only if the floating- 
point number is negative. : 


e An 11-bit biased exponent. 
e A 52-bit mantissa with the high-order 1 bit hidden. 
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A floating-point number is represented by the form: 


sign exponent-bias 
(-1) * 2 * 1.fraction 


where fraction is the pattern of bits in the mantissa. 


Representation of Extreme Numbers 


zero (signed) is represented by an exponent of zero and a mantissa of 
Zero. 
signed infinity (or affine infinity) is represented by the largest value that the 


exponent can assume (all ones), and a zero mantissa. When 
infinity is printed, it appears as +INF or —INF. 


Not-a-Number (NaN) is represented by the largest value that the exponent 
can assume (all ones), and a non-zero mantissa. The sign is 
usually ignored. When NaN 1s printed, it appears as QNaN 
(for guiet NaN), or SNaN (for signalling NaN). 


denormalized numbers are a product of gradual underflow. They are non-zero 
numbers with an exponent of zero. The form of a denor- 
malized number is: 


exponent-biastl 
2 * @.fraction 


where fraction is the number of bits in the mantissa. 


Normalized numbers are said to contain a hidden bit, providing for one more bit of 
precision than would normally be the case. To understand the reason for this, you 
need to understand the process of normalization. 


Unnormalized numbers are generated as intermediate results during most floating- 
point operations, and they must be normalized before they can be processed further. 
Normalization of an unnormalized number consists of repeatedly shifting the 
mantissa left or right with the corresponding decrement or increment, respectively, of 
the exponent field. This process is repeated until the most significant on bit of the 
mantissa is in the most significant bit of the mantissa field. At this point, one more 
shift left 1s performed along with a corresponding decrement of the exponent field. 
The leading on bit of the mantissa is lost and, therefore, not represented explicitly. 


Denormalized numbers may be thought of as unnormalizable because the exponent 


field is already so small that the left-shift decrement cannot be performed. Conse- 
quently, denormalized numbers do not have a hidden bit. 
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Arrays 


Pointers 


Structures 


Arrays are stored in row major order, such that the last subscript in a multi- 
dimensional array varies fastest. For example, an array dimensioned as: 


x[3][2] 
is stored in this order: 


x[O][0], xLOj[1], x{1] [0], xf] [1], x{2] [0], x{2] [1] 


Pointers occupy four bytes and are unsigned. The NULL value pointer is repres- 
ented by zero (0). All arithmetic on pointers is computed with four bytes of accu- 
racy. 


Structure members are stored sequentially in the order in which they are declared. 
The first member is stored at an offset of zero relative to the address of the struc- 
ture. Subsequent members are given the next available offset consistent with their 
size. Since char and unsigned char occupy a single byte, members of these types are 
given the next free byte. Larger sized members, including those of type int and float 
are assigned the next available doubleword offset. The struct and union variables are 
aligned according to the maximum alignment of their members. Bytes that are 
skipped are not reused to store subsequent char values. 


Bit fields are assigned bits within the next available doubleword beginning at the 
least significant bit. Subsequent bit fields are kept in adjacent bits, if they will fit in 
the same doubleword. If not, the upper portion of the current doubleword 1s left 
unused, and the bit field is assigned the least significant portion of the next 
doubleword. 
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This chapter describes how the AIX RT PC C Compiler represents data in storage. 


It also describes characteristics of the C data types as defined by the C Compiler. 
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Data Representations on RT PC 
The following terms are used as defined by the IBM processor: 


e A byte contains 8 bits. 
e A halfword contains 16 bits. 
e A word or fullword contains 32 bits. 


The following example shows the byte order of a halfword and fullword stored in 


memory: 
15 ] | 0) 
address n n+1 
31 0 
iovere] moe 
address n n+1 n+2 n+3 


The RT PC microprocessor requires alignment of data. For this reason, the AIX 
RT PC C Compiler aligns 2-byte entities on even addresses and 4-byte entities on 
addresses which are multiples of 4; 8-byte entities are aligned on addresses which are 
multiples of 4. | 


Integral Representation 


The following information describes characteristics of the integral data types 
including the storage size in number of bits, the range of values represented by the 
data type, and the alignment. Two’s complement format is used for all signed 
integer types. 


char 0 to 255 byte 
unsigned char 


bit 









~ 
>) 


byte 0 
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-32768 to 32767 | halfword 


bit 15 14 0 


| byte 0 | byte 1 


sign 





short 
short int 





Note: An external short data type is fullword aligned. 


unsigned short 16 0 to 65535 halfword 
unsigned short int 


bit 15 


0 


Note: An external short data type is fullword aligned. 


int -2147483648 to fullword 




























long 2147483647 
long int 





bit 31 30 0 


Tore 0 [wee one [es 


sign 


its 
unsigned 32 0 to 4294967295 fullword 
unsigned int 
unsigned long 
unsigned long int 


















bit 31 0 
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Floating-Point Representation 


The following information describes characteristics of the floating-point data types. 
The AIX C Compiler supports both single and double precision floating-point data, 
according to the ANSI/IEEE 754-1985 standard. 


Single Precision 










float 32 Approximately fullword 
-3.37e +38 to 
3.37e + 38 





bit 31 30 23 22 0 


Mantissa(23+1 bits) 









sign 
Exponent,biased by 127 


The three fields of a single-precision floating-point number are: 


e A sign bit designated by sin the diagram. The sign bit is 1 only if the floating- 
point number is negative. 


e An 8-bit biased exponent. 
e A 23-bit mantissa with the high-order 1-bit hidden. 


Double Precision 














double 64 Approximately fullword 
long double -1.67e + 308 to 





1.67e + 308 





bit 63 62 52 51 0 


Sign | Mantissa(52+1 bits) 





Exponent, biased by 1023 


The three fields of a double-precision floating-point number are: 


e A sign bit designated by sin the diagram. The sign bit is 1 only if the floating- 
point number is negative. 


e An 11-bit biased exponent. 
e A 52-bit mantissa with the high-order 1 bit hidden. 
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A floating-point number is represented by the form: 


sign exponent-bias 
(-1) * 2 * 1.fraction 


where fraction is the pattern of bits in the mantissa. 


Representation of Extreme Numbers 


zero (signed) is represented by an exponent of zero, and a mantissa of 
Zero. 
signed infinity (or affine infinity) is represented by the largest value that the 


exponent can assume (all ones), and a zero mantissa. When 
infinity is printed, it appears as +INF or —INF. 


Not-a-Number (NaN) is represented by the largest value that the exponent 
can assume (all ones), and a non-zero mantissa. The sign is 
usually ignored. When NaN is printed, it appears as QNaN 
(for guiet NaN), or SNaN (for signalling NaN). 


denormalized numbers are a product of gradual underflow. They are non-zero 
numbers with an exponent of zero. The form of a denor- 
malized number 1s: 


exponent-biastl 
2 * Q.fraction 


where fraction is the number of bits in the mantissa. 


Normalized numbers are said to contain a hidden bit, providing for one more bit of 
precision than would normally be the case. To understand the reason for this, you 
need to understand the process of normalization. 


Unnormalized numbers are generated as intermediate results during most floating- 
point operations, and they must be normalized before they can be processed further. 
Normalization of an unnormalized number consists of repeatedly shifting the 
mantissa left or right with the corresponding decrement or increment, respectively, of 
the exponent field. This process is repeated until the most significant on bit of the 
mantissa is in the most significant bit of the mantissa field. At this point, one more 
shift left is performed along with a corresponding decrement of the exponent field. 
The leading on bit of the mantissa is lost and, therefore, not represented explicitly. 


Denormalized numbers may be thought of as unnormalizable because the exponent 


field is already so small that the left-shift decrement cannot be performed. Conse- 
quently, denormalized numbers do not have a hidden bit. 
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Arrays 


Pointers 


Structures 


Arrays are stored in row major order, such that the last subscript in a multi- 
dimensional array varies fastest. For example, an array dimensioned as: 


x[3][2] 
is stored in this order: 


x{1]L1], x{1][2], x[2] [1], xf2][2), x(3] [1], x[3][2] 


_ Pointers occupy four bytes and are unsigned. The NULL value pointer is repres- 


ented by zero (0). All arithmetic on pointers is computed with four bytes of accu- 
racy. 


Structure members are stored sequentially in the order in which they are declared. 
The first member is stored at an offset of zero relative to the address of the struc- 
ture. Subsequent members are given the next available offset consistent with their 
size. Since char and unsigned char occupy a single byte, members of these types are 
given the next free byte. Larger sized members, including those of type int and float 
are assigned the next available fullword offset. The struct and union variables are 
aligned according to the maximum alignment of their members. Bytes that are 
skipped are not reused to store subsequent char values. 


Bit fields are assigned bits within the next available fullword beginning at the most 
significant bit. Subsequent bit fields are kept in adjacent bits, if they will fit in the 
same fullword. If not, the upper portion of the current fullword is left unused, and 
the bit field is assigned the least significant portion of the next fullword. 
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About This Chapter 
This chapter describes how the AIX System/370 C Compiler represents data in 
storage. It also describes characteristics of the C data types as defined by the C 
Compiler. 


© Copyright IBM Corp. 1989 5-1 


Data Representations on System/370 
The following terms are used as defined by the IBM System/370 architecture: 


e A byte contains 8 bits. 
e A halfword contains 16 bits. 
e A word or fullword contains 32 bits. 


The following example shows the byte order of a halfword and fullword stored in 


memory: 
0 8 15 
sadness n nt+1 
0 31 
[ore] | over 
saaneet n n+] n+2 nt+3 


The System/370 architecture requires alignment of data. For this reason, the AIX 
System/370 C Compiler aligns 2-byte entities on even addresses and 4-byte entities 
on addresses which are multiples of 4; 8-byte entities are aligned on addresses which 
are multiples of 4. 


integral Representation 


The following information describes characteristics of the integral data types 
including the storage size in number of bits, the range of values represented by the 
data type, and the alignment. 


char 0 to 255 byte 
unsigned char 


bit 






(<>) 
~™ 


byte 0 


Data Type | Bits Range Alignment 
short 


16 -32768 to 32767 halfword 
short int 


bit 0 1 15 


oreo [ one 


sign 
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unsigned short 16 0 to 65535 halfword 
unsigned short int 


bit 0 15 
byte 0 | byte 1 
Data Type 


int 
long 
long int 


-2147483648 to fullword 

















2147483647 


bit 


0 1 31 
| byte 0 | byte 1 ; byte 2 | byte 3 






sign 
unsigned 32 0 to 4294967295 fullword 
unsigned int 
unsigned long 
unsigned long int 
bit 0 31 


byte 0 | byte 1 | byte 2 
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Floating-Point Representation 


The following information describes characteristics of the floating-point data types. 
The AIX C Compiler supports both single and double precision floating-point data, 
according to System/370 architecture. 


Single Precision 


oa —_ 


5.4e-75 to 
Characteristic 6-digit fraction 


V2etAD 
sign 
















The three fields of a single-precision floating-point number are: 


e A sign bit designated by s in the diagram. The sign bit is | only if the floating- 
point number is negative. 


e A 7-bit characteristic 


e A 24-bit 6-digit fraction. 


Double Precision 





double 64 See “Single fullword 
long double , Precision” 


Sign 














The three fields of a double-precision floating-point number are: 


e A sign bit designated by sin the diagram. The sign bit is 1 only if the floating- 
point number is negative. 


e A 7-bit characteristic. 


e A 54-bit 14-digit fraction. 


Please refer to IBM System 370 Principles of Operation for more details. 
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Arrays 


Pointers 


Structures 


Arrays are stored in row major order, such that the last subscript in a multi- 
dimensional array varies fastest. For example, an array dimensioned as: 


x[3][2] 
is stored in this order: 


xC1{1], xf1[2], x[2][1], xf2][2), x[3] [1], x[3] [2] 


Pointers occupy four bytes and are unsigned. The NULL value pointer ts repres- 
ented by zero (0). All arithmetic on pointers is computed with four bytes of accu- 
racy. 


The size of a struct or union is dependent upon whether the compiler generates 
padding to align members. The compiler generates such padding by default if the 
toggle Align members is on, and does not do so by default if the toggle is off. 


The size of an unpadded union is the size of the biggest member. The size of a 
padded union is the size of the biggest member, padded so that its size is evenly 
divisible by its alignment. 


The size of an unpadded struct is the sum of the sizes of its members. Non-bit-field 
members always start on byte boundaries, and there is no padding between 
members, except in the case of bit members. The size of a padded struct is the sum 
of the sizes of its members, including alignment padding between members. It is 
padded so that its size is evenly divisible by its alignment. 


Notes: 


1. A struct or union is aligned according to the most stringent requirements among 
its members. 


2. The size of enum types depends on the status of the Long_enums toggle. If the 
toggle is Off, the type is mapped to the smallest of a byte, half word, or full 
word, such that all the values can be represented. If the toggle is On, the enum 
maps to a full word (matching the Portable C Compiler convention). See “Com- 
piler Toggles (AIX/370)” on page 2-11. 
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Storage Classes 


Each static variable is placed in either the BSS section or the DATA section — the 
latter if it 1s initialized. 


Each global variable with no extern specifier that is not initialized is defined as a 
common block; if it is initialized, it is mapped into the DATA section and given the 
global attribute. Each extern variable is given the global and undefined attributes. 
Each local static variable is placed in either the BSS section or the DATA section. 


Each auto variable is assigned either to a machine register or to storage in the rou- 
tine’s stack frame. The compiler attempts to place each auto-classed variable in a 
register provided the variable’s type is appropriate and its address is not required. In 
a function containing calls to setjmp, auto variables are not mapped to registers, so 
that their values are not lost across such calls. 
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This chapter describes the conditions, rules, and conventions that the user or pro- 
grammer must observe when mixing program elements of two or more AIX PS/2 
high-level languages. Detailed information is provided for the VS FORTRAN, VS 
Pascal, and C Compilers on the PS/2. 


Mixing Languages on PS/2 


The IBM AIX PS/2 language system permits the mixing of elements from different 
languages in a single program. This chapter assumes you are familiar with the lan- 
guages you want to mix; the elements of the languages are not described here in 
detail. Appendix C, “Program Examples for Mixing Languages” gives sample pro- 
grams that show how to pass parameters between different languages. 


Correspondence of Data Types 


The data types of one language are.usually quite different from the data types of 
another language. Also, the way data is stored is not the same across languages; the 
internal data representation is left unspecified and usually varies with the implemen- 
tation. 


However, a certain amount of similarity among the data types of the different lan- 
guages exists since the languages share many system primitives and since [IEEE! 
standard data representations are used as much as possible. Table 6-1 shows some 
of the correspondence among languages. 


Table 6-1. Correspondences of Data Types Among Languages 


FORTRAN FORTRAN 
IBM and R1 Modes VX Mode 






Logical*1 Logical*1 Boolean 
Logical*2 
Logical, 

Logical*4 


Logical, 
Logical*4 


Integer* 1 Integer*1 


Byte 


packed/unpacked 
CHAR element 


signed char 






short 


Integer*2 Integer*2 


Integer*4 Integer*4 Integer int 


Real, Real, Shortreal 
Real*4 Real*4 


Real*8 Real*8 


float 


Real double 


long double 





Complex Double Precision, 


Complex 


Complex*8 Complex*8 


Complex* 16 Complex*16 


Character Character packed array of char 


Char 


String 


Note: Table 6-1 shows how the languages represent data internally in the computer’s 
memory rather than how data are passed between program units. 





1 JEEE 754 Floating-Point Standard 
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As Table 6-1 shows, some data types do not exist in the other languages. When you 
interface languages, make sure you either avoid mismatching data types or use the 
mismatches very cautiously. When data types do correspond, the interfacing of the 
languages is more straightforward. 


Most numeric data types have counterparts across the languages. However, char- 
acter and string data types do not. The most difficult aspect of language interfacing 
is the passing of character, string, or text variables between languages. 


Character Variables 


FORTRAN’s only character variable type is Character, which is stored as a set of 
contiguous bytes, one character per byte. The length of a FORTRAN character var- 
iable or character Array element is determined at compile time and is, therefore, 
static. Character lengths are returned by the FORTRAN intrinsic function LEN. 


When a FORTRAN character variable is passed as a parameter, the address of the 
beginning of the character is passed along with a hidden parameter which is the 
static length of the character string. The hidden parameter is added to the end of 
the declared parameter list. 


Pascal’s character-variable data types are String and packed array of Char. The 
String data type has a 4-byte double word-aligned string length followed by a set of 
contiguous bytes, one character per byte. The dynamic length of the string can be 
determined using the length function. However, packed array of Char, like the type 
Character in FORTRAN, is stored as a set of contiguous bytes, one character per 
byte. 


C character data is typically stored as arrays of type char. The char data type stores 


one character per byte; therefore, an array of char is stored exactly like a 
FORTRAN Character variable or a Pascal packed array of Char. 
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Storage of Matrices 


FORTRAN matrices are stored in computer memory by column (column major 
order); therefore, the first subscript in a multi-dimensional array varies fastest. An 
array dimensioned as: 


A(3,2) 
is stored in this order: 
A(1,1) A(2,1) A(3,1) A(1,2) A(2,2) A(3,2) 
Pascal and C matrices are stored in computer memory by row (row major order). 
For example, an array in Pascal declared as: 
A: array [1..3,1..2] of Real 
is stored in this order: 
AT1,1] A[1,2] A[2,1] A[2,2] A[3,1] A[3,2] 
Since the matrix storage convention for Pascal and C differs from that for 


FORTRAN, be careful when passing references to matrices between FORTRAN 
and the other languages. 


Input/Output Primitives 


Primitive input/output routines are contained in the language run-time libraries. 
They are bound to your program during the final linking process by the AIX linker 
ld. 


When you compile a program using the ce or vs command, the appropriate libraries 
are linked in the proper order. The libraries are: 


a 


VS Pascal libvssys.a 
libe.a 

VS FORTRAN libvsfor.a 
libvssys.a 
libe.a 


The input/output primitives are different for each language; because of this you are 
not able, for example, to open a file or device for use by one language and write to 
it or read from it in a different language. Generally, however, two languages can 
exist in a program as long as they each have their own files and device for 
input/output, which includes the console device. 











Input/Output Initialization: When mixing languages, special handling is required 
when calling AIX VS Pascal or FORTRAN subroutines that perform input/output. 
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An initialization routine must first be called from the main program so that the 
input/output buffers and floating-point information are properly set up. These rou- 
tines do not require parameters. The initialization routines and run-time libraries in 
which they are contained are: 


Language of Initialization 
Called Routine Routine Library 


VS FORTRAN libvsfor.a 


Input/Output Termination: If aC function is called from a AIX VS FORTRAN or 
Pascal main program, the termination routine vstio in libvssys.a must be called upon 
to return from the C function to properly flush the input/output buffers. 





Whenever you mix languages, you need first to become familiar with the require- 
ments of each particular subroutine and each language’s argument-passing require- 
ments. 


Designation of Entry Points and Other Global Symbois 


An entry point is the address of the first instruction of a subroutine or function. If 
an entry point is not known at compile time, the relative entry point is determined at 
link time when all the separately compiled routines are brought together with the 
system library (or libraries) to produce an executable binary file. 


An entry-point reference in FORTRAN is designated in a CALL statement or by the 
invocation of a function in an expression. An entry-point reference in Pascal is des- 

ignated by a procedure or function call, and in C by a function call. An entry-point 

reference in Assembler code is designated by a reference to an external symbol. 


When compiled programs are linked, the entry points referenced in a calling 
program cause the linker to add an entry to a table of symbols. The linker then 
needs to associate a start address with each symbol in the table, which it does when 
it finds the called routine. The entry point for a called FORTRAN routine is desig- 
nated by a subroutine or function declaration. The entry point for a called Pascal 
routine is designated by a procedure or function declaration at the global scope. 
The entry point for a called C function is designated when the function is defined. 
The entry point for a called Assembler routine is designated by a global declaration. 


When compiled program units of mixed languages are linked together, it 1s impor- 
tant to note that the compilers may maintain different numbers of significant charac- 
ters in global names, which include entry points. Also, all local and global names in 
FORTRAN and Pascal are made lowercase. As a result, for example, a FORTRAN 
and a Pascal program cannot call a C function whose name is not all lowercase. 

The AIX PS/2 C compiler creates external symbols which are in the same case as the 
user has declared them. Thus a C routine declared as Upper cannot be called from 
FORTRAN or Pascal since both compilers would produce an external symbol upper 
regardless of the user specified name. 


The entry-point name you assign to local Pascal procedures (not visible in the global 
scope) stays the same. 
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Argument-Passing Mechanisms 


When control is passed from one routine to another by a call, operands for the 
called routine to act upon are usually also passed. When finished, the called routine 
usually has results to report and needs to know where control is to be returned in 
the calling routine. The AIX PS/2 language system provides this information by 
using one or both of the following: 


¢ Intel 80386 or Intel 80387 registers 


e Data structure known as the stack. 


The 80386 Registers 

The AIX PS/2 Operating System is built around the Intel 80386 microprocessor, 
which has sixteen 32-bit internal registers. Table 6-2 contains more information on 
these registers: 












Table 6-2. 80386 Registers 


EAX EBP 
EBX ESP 
ECX ESI 
EDX EDI 










Type 


General purpose registers 


Logical and arithmetic 
operations. 
Address computations2 




























CS ES Segment registers? Initialized by operating 
DS FS system and should not be 
SS GS changed. 








The 80387 Registers 


The Stack 


AIX PS/2 floating-point performance is optionally provided by the Intel 80387 
floating-point numeric processor. The presence of the Intel 80387 chip is determined 
at the time of the first floating-point instruction for a given process. If the optional 


80387 chip is not installed in the system, then the behavior of the 80387 chip is 
exactly duplicated by software emulation. This emulation is transparent (other than 


at execution time) to you. The 80387 chip has a floating-point stack architecture 
which consists of eight 80-bit extended precision registers. 


Although it is not important to be familiar with the stack when coding in only one 
language, it is helpful when languages are being interfaced. The stack is a last-in 
first-out data structure that is located, initialized, and used by the AIX PS/2 lan- 
guage system. Stacks are thought of as having information pushed onto them and 
having information popped off them. This is because each time a routine is called, 
the compiler pushes information about the calling arguments followed by the return 
address onto the stack. If routines call other routines before a return is made, the 


2. The exception is ESP which may be used as an index operand. 


3 A flat address model has been adopted by the AIX PS/2 Operating System which results in a real address space of 4 
gigabytes. The segmented features of the Inte] 80386 chip architecture are not used. 
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stack continues to grow; as control returns to the calling routines, the stack becomes 
smaller. The called routine removes the return address and the local data space. 
The parameter list of the called routine is popped off the stack by the calling 
routine. 


The physical memory address of the stack is usually not relevant. The stack grows 
toward smaller absolute addresses, so pushing data onto the stack consists of decre- 
menting the value stored in ESP and writing to the address in memory indicated by 
ESP. 


The data written to the stack by the calling routine depends both on the language 
and on the data type of the arguments being passed to the called routine. Usually 
either the addresses of the arguments (used in the call-by-reference mechanism) or 
the values of the arguments (used in the call-by-value mechanism) are placed on the 
stack. The languages also place a 4-byte return address on the stack, which is the 
last item pushed on to the stack by the calling routine. This return address indicates 
where execution is to resume after the called routine finishes executing. 


Subroutine Linkage Convention 
The AIX PS/2 language system adheres to the following linkage convention: 
















Table 6-3. AIX PS/2 Language Linkage Convention 


EAX Scratch registers Need not be preserved 
ECX 
EDX 


EBX 
ESI 


EDI 
Must be restored at the end of a call 


ESP Stack pointer Should not be popped by called 
routine 


All parameters are passed in reverse order and the calling routine has the responsi- 
bility for cleaning up the stack. 

















Register variables Must be preserved across calls 






Routines written in FORTRAN, Pascal, and C respect these register usage con- 
ventions by preserving the registers listed in Table 6-3 to the states they were in 
before their call. All routines used with the AIX PS/2 languages must also preserve 
these registers. 


Parameter-Passing Convention 
For ease of language interfacing, all AIX PS/2 languages follow the same calling 
convention. Parameters are passed to the called routine on the stack. They are 
pushed onto the stack in the reverse order from the way that they were declared. 
That means the last parameter is pushed first on the stack, and the first parameter is 
pushed last. 
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Function Results 


Stack Frame 


All arguments to FORTRAN subroutines and functions are passed by reference. 
For every argument except a character argument, a 32-bit pointer to the object is 
pushed onto the stack. Character parameters are passed as a 32-bit pointer to the 
Character object. A 32-bit value which is the static length of the Character object is 
passed at the end of the actual argument list. 


In Pascal, if the called procedure is not a procedure or function at the global level, 
the static link is the last thing pushed onto the stack before the routine is called. 
Pascal call by reference parameters always have a 4-byte pointer to the variable 
pushed onto the stack. Pascal call by value parameters are pushed onto the stack. 
Pascal Reals are pushed onto the stack as 8 bytes. Pascal sets are pushed onto the 
stack with the least significant element in the least significant word. Thus, the repre- 
sentation of a set on the stack is the same as the representation in memory. Ifa 
Pascal value parameter is longer than 4 bytes and not a double or a set, the address 
of the data is pushed onto the stack, and the called procedure or function copies the 
data into local storage. 


Pascal procedure and function parameters are pushed as follows: the address of the 
procedure or function is pushed onto the stack. The static link is then pushed onto 
the stack if the procedure or function is not at the global level. If the procedure or 
function is at the global (outermost) level, the value 0 (nil) is pushed onto the stack 
instead of the static link. 


All arguments to C functions are passed by value. Actual arguments which are 
expressions are evaluated before the function reference. The result of the expression 
is then pushed onto the stack. Arrays are passed by the address of the first element 
of the array as a 4-byte quantity. 


All C arguments except double, struct and union arguments are passed as four-byte 
values; double arguments are passed as eight-byte values. All float values are passed 
as doubles.. The struct and union arguments are passed by value, regardless of the 
number of bytes required to pass the argument. 


When C functions which return structs or Pascal functions which return records are 
called, the calling routine allocates sufficient space for the structure and passes a 
hidden first parameter to the called routine. Remember, the first parameter is the 
last one pushed on the stack. This parameter is a pointer to the allocated space. 


The AIX PS/2 languages return the results of functions in register EAX for non- 
floating-point values. Floating-point values are returned at the top of the Intel 

80387 floating-point stack. C functions which return structs or Pascal functions 
which return records return a 32-bit pointer to the struct or record in EAX. 


A typical stack frame for a function call is created by the following sequence: The 
caller pushes the function arguments in reverse order (right to left) from the function 
declaration. If the called routine returns a C struct or Pascal record, then the caller 
pushes the address of a buffer allocated by the caller for the struct or record. The 
return address is pushed on the stack by executing the call instruction. The base 
pointer register EBP is pushed and EBP is made to point to the stack top, which 
now contains its old value. The called function allocates all of its local data space. 
If the allocated registers need to be used in the called routine, then their values may 
be saved on the stack. The return result is loaded into the EAX register for non- 
floating-point values. C functions returning a struct and Pascal functions returning a 
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record load the address of the buffer into EAX. Floating-point values are returned 
at the top of the 80387 numeric processor stack. If the registers EBX, EDI, and ESI 
were saved, then they are restored. The called function then reloads the original 
value of the EBP register, removes its local space from the stack, and returns. The 
caller pops the arguments off the stack. 


The following diagram illustrates a typical stack frame after a function call: 


Higher Addresses 


caller's EBP 
<+—— EBP 


caller's ESI, EDI, EBX (saved if necessary) 


<A ESP 





Lower Addresses 


Figure 6-1. Typical Stack Frame 


FORTRAN Argument-Passing Conventions 
FORTRAN uses the call-by-reference mechanism for passing arguments. This 
means that a 4-byte address of each argument is pushed onto the stack from the last 
argument to the first when a call is made. The return address of the calling program 
unit is pushed onto the stack after the last argument address. 


Character data types in FORTRAN are treated differently. When an argument is a 
character variable, 8 bytes are placed on the stack: a 4-byte address in the location 
of the argument in the argument list and the 4-byte static character count of the 
variable at the end of the argument list. This length is the size of the variable made 
known to the compiler by the character type specification, and is not the number of 
characters that happen to be stored in the variable. 


When an array is passed as an argument in a subroutine call or external function 
reference, the address of the first byte of the first element is pushed onto the stack. 
If an element of an array is passed as an argument, the address of that element is 
pushed. 


Actual arguments that are expressions are evaluated before the subroutine call or 
function reference. The result of the expression is assigned to a temporary storage 
location and the address of the location is pushed onto the stack. When storing a 
numeric expression, the temporary storage location is usually 4 bytes (8 bytes for 
double-precision values). 
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When an external function is referenced, the result is returned in register EAX (or at 
the top of the floating-point stack if the result is a floating-point number). One 
exception to this occurs if the external function returns character data. In this case, 
the 4-byte address of the result is returned in register EAX. 


When the called program unit finishes its computation, the stack must be cleaned up 
so that it does not continue to grow indefinitely. When control is returned to the 
calling function, all arguments are discarded from the stack. 


Example A: 


Character*5 STR 

Integer DWORD 

A=5.0 

CALL XYZ(4.0*A,STR,DWORD) 


END 
When the call in Example A is made, the 4-byte integer 5 is pushed onto the stack. 
This value is the static length of STR. The address of the 4-byte variable DWORD 
is then pushed onto the stack. Then the address of the beginning of the character 
string is pushed onto the stack. Then the expression (4.0*A) is evaluated and a tem- 
porary storage location is set up for it. The address of this location is the last 


parameter you pushed onto the stack. Lastly, the return address in the calling 
program unit is stored in 4 bytes. 


Figure 6-2 on page 6-11 illustrates a stack after the call in Example A is made (msb 
and 1sb indicating the most and least significant bytes, respectively). 
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Higher Addresses 


Byte count of STR (5) 
stored in 4 bytes. 


Address of the first byte of 
DWORD stored in 4 bytes. 


Address of the first byte of 
STR stored in 4 bytes. 


Address of the first byte of 
the evaluated expression (20.0) 
stored in 4 bytes. 


Return address 
stored in 4 bytes. 
top of stack 


ESP 





Lower Addresses 


Figure 6-2. Stack After Call in Example A 


Upon return, since it is the responsibility of the calling routine to pop the arguments 
off the stack, the stack pointer in this example should be pointing to the least signif- 
icant byte of the 4-byte address of the temporary expression. The return address is 
popped off by the called routine along with the local space used by the routine. The 
calling routine cleans up the stack by removing the parameters after control is 
returned. 


Although FORTRAN allows the names of subroutines and external functions to be 
passed as arguments in subroutine calls and function references, you should avoid 
doing this when interfacing FORTRAN with another language. 


Pascal Parameter-Passing Conventions 
Pascal uses either the call-by-value or the call-by-reference mechanism for passing 
parameters. The mechanism used depends on the data type specified for the param- 
eter in the procedure or function being called. If the parameters are pointers to 
other structured data, addresses of structured data get pushed onto the stack. When 
this happens, the pointer function (@) combined with the call-by-value mechanism 
performs the same way as the call-by-reference mechanism. 


Pascal defines five parameter types: 


e variable 

e value 

* const 

e function 

¢ procedure. 
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The last two refer to the passing of function and procedure names as parameters in a 
function or procedure call. They are not further described here since this chapter 
deals with the calling of routines in languages other than Pascal where the parameter 
type may not even be defined. 


Variable Parameters 


‘Value Parameters 


Variable parameters are specified by including var with the names of the formal 
parameters in the procedure or function definition statement. The actual parameters 
must also be declared in a var declaration statement by the time the procedure or 
function is called. The parameters are passed by the call-by-reference mechanism 
and the 4-byte address of the data structure is placed on the stack. 


Value parameters are specified by the absence of var with the names of the formal 
parameters in the procedure or function definition statement. When the procedure 
or function is called, the actual parameters can be an expression, a constant, or even 
a variable that was declared in a var declaration statement. A value parameter also 
falls into one of these three categories: set, double, and other. 


For set value parameters, a calling routine always uses the call-by-value mechanism; 
the parameters are pushed onto the stack regardless of their length. For example, a 
set that occupies 1 byte of storage is pushed as a byte onto the stack. A set that 
occupies more than 1 byte of storage is pushed with the least significant element in 
the least significant word which is at the lowest absolute address. Thus, the repre- 
sentation of a set on the stack is the same as its representation in memory. 


For double value parameters, a calling routine always uses the call-by-value mech- 
anism; usually 8 bytes are pushed onto the stack in such a way that the represen- 
tation of a double value on the stack is the same as in memory, that is, with the sign 
bit in the highest address byte. 


A Pascal value parameter longer than 4 bytes is passed by its address. This last case 
is actually a call-by-reference, but Pascal requires the called procedure or function to | 
copy the data into its local storage. This is done so that the data associated with the 
parameters in the calling routine remain unchanged when the data are manipulated 
by the called routine, as is true with the normal call-by-value mechanism. 


Arrays that are referenced in a procedure or function call are considered value 
parameters longer than 4 bytes. However, whether a value or an address is placed 
on the stack depends upon the procedure or function declaration statement. If the 
declaration statement specifies the parameter as an array, the address of the first 
byte of the array is placed on the stack in 4 bytes, and the called routine has to copy 
the entire array into its local storage. If the declaration statement does not specify 
the parameter as an array, the value of the element is placed on the stack. 
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Example B: 
program PASS; 


type 
ARAY = array [1. . 20] of Real; 
var 
A : ARAY; 
procedure 
APAS(var X : Real); external; 
procedure 
BPAS(var X : ARAY); external; 
procedure 
CPAS ( X : Real); external; 
procedure 


DPAS ( X : ARAY); external; 


begin 
A[2] := 2.; 
APAS(A[2]); 
BPAS(A[2]); 
CPAS(A[2]); 
DPAS(A[2]); 
end. 


These procedures have been made external to simplify the example; declaring the 
procedures external tells the compiler that they exist in a different file. 


In Example B, the calls to APAS and BPAS cause the 4-byte address of the second 
element of the array A to be pushed onto the stack because the single parameter to 
these procedures is a variable, which is declared in the procedure declaration state- 
ment. The call to CPAS places the 4-byte value of A[2] on the stack because the pro- 
cedure declaration statement specifies a non-variable real number. 


The call to DPAS in the example causes the 4-byte address of the second element of 
the array A to be pushed onto the stack. This occurs because the procedure declara- 
tion statement identifies the parameter of DPAS as the first element of an array that is 
to be passed by the call-by-value mechanism. The address of the start of the array is 
passed, and the procedure copies the array into its local storage area. 


Const Parameters 
Const parameters are specified by including const with the names of the formal 
parameters in the procedure or function definition statement. Any expression, vari- 
able, or constant may be passed by const. No attempt should be made to modify the 
actual parameter while it is being passed by const. 


General Pascal Considerations 
In addition to the five parameter types, Pascal also defines hidden parameters. They 
are not user specified; they exist for compiler implementation reasons only. Hidden 
parameters are defined in the following cases: 


e A parameter is inserted after each instance of a conformant string in the formal 
argument list. It has a value equal to the corresponding actual argument’s 
declared string length. 


e An extra parameter appears as the last argument in the parameter list of func- 
tions which return structures or strings. It holds the address of the function 
result. 
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e A parameter is inserted after each instance of a file type variable. This hidden 
parameter contains file naming information which is required by the VS Pascal 
run-time library routines. 


As indicated previously, either the values or the addresses are pushed onto the stack 
by the Pascal compiler in the reverse order in which they are declared in the proce- 
dure or function declaration. After the parameter information is pushed onto the 
stack, the 4-byte return address is pushed and the stack pointer points to that 
address. Then, if the procedure or function is global, the value nil (0) is pushed onto 
the stack as the final item before the routine is called. If the called routine is not a 
global procedure or function, a 4-byte address known as the static link is pushed 
onto the stack as the final item. The static link is an address for the called routine 
that indicates the location of the variables in the routine which lexically encloses it. 


Static links complicate the mixing of Pascal with other languages and can be avoided 
by declaring the called routines as external procedures or functions in the Pascal 
main program. This declaration, which makes the called routine globally defined, 
must be in the Pascal main program even if the other language routines are refer- 
enced only by a separately compiled Pascal procedure. 


Function results are returned in register EAX or at the top of the Intel 80387 
floating-point stack if the value is a floating-point number (single or double preci- 
sion). 


When the called procedure or function finishes its execution, the stack must be 
cleaned up. All parameters are discarded from the stack by the calling routine after 
control is returned. 


Example C: 


program SAMPLE; 
type 
STR = packed array [1. . 20] of Char; 
var 
A : Reals 
I: Integer; 
So: STR; 
procedure 
FSUB(var ARG] : Real; 
var STG : STR; 
input : Integer); external; 


begin 
T:=5; 
A:=100.5; 
S:=' This is a string. '; 
FSUB(A,S,1); 
end. | 
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Figure 6-3 illustrates a stack after the call in Example C is made (msb and 1sb indi- 
cating the most and least significant bytes, respectively): 


Higher Addresses 


The value of I, 
stored in 4 bytes. 


The address of string S, 
stored in 4 bytes. 


The address of variable A, 
stored in 4 bytes. 


Return address 
stored in 4 bytes. 





Lower Addresses 


Figure 6-3. Stack After Call in Example C 


Upon return, since it is the responsibility of the calling routine to pop the parameters 
off the stack, the stack pointer in this example should be pointing to the least signif- 
icant byte of the address of A. The return address is popped off by the called 
routine. The calling routine cleans up the stack after control is returned. 


C Argument-Passing Conventions 
The C Language uses the call-by-reference mechanism for passing arguments 
declared as arrays and uses the call-by-value mechanism for passing other arguments. 
When you use the address of operator (&), these other arguments may be pointers to 
other structured data, in which case the addresses of the structured data get pushed 
onto the stack. This pointer function combined with the call-by-value mechanism 
performs the same way as the call-by-reference mechanism. 


The compiler does not treat as arrays those arguments that lack indices. If an actual 
argument includes an index, it specifies an element of an array. 


Example D: 


main () 

{ 
int x[5]; 
x[Q] = 100; 
funcl(x); 
func2(x[0]); 
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In Example D, the call to funcl causes the 4-byte address of the first byte of the first 
element of array x to be pushed onto the stack. The call to func2, however, causes 
4-byte value of the first element of array x (the number 100) to be pushed onto the 
stack. An actual argument that is an expression is evaluated before the function 
reference and its value is pushed onto the stack. All arguments except struct, union, 
double, and float arguments are pushed onto the stack as 4-byte values; double and 
float arguments are pushed as 8-byte values; actual arguments are pushed onto the 
stack in the reverse order that they are declared in the function declaration. The last 
item pushed onto the stack is always a 4-byte return address in the calling routine. 


Functions in C Language need not return results; when they do, the non-floating 
point results are returned in register EAX. Floating-point values are returned at the 
top of the 80387 numeric processor stack. Upon return from a function, the argu- 
ments passed to the function are still on the stack, though their values may have 
been altered by the function. It is the calling routine’s responsibility to pop the 
arguments off the stack. 


Example E: 


main () 

{ 
int I; 
Short J,K; 
char str[6]; 
float x; 
double dx; 


I = 15; 

J = 42; 

K = 59; 

str[O] = 'H'; str[1] = 'e'; 

str[2] = 'l'; str[3] = '1'; str[4] = 'o'; 
str[5] = '\0'; 

x = 100.; 

dx = 99.e-2; 


xfunc(1,J,&k,str,x,dx); 
} 


Figure 6-4 on page 6-17 illustrates how the stack looks after the call in Example E 
is made (msb and 1sb indicating the most and least significant bytes, respectively). 
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Higher Addresses 


Value of dx 
stored in 8 bytes. 


Value of x, promoted 
to double, stored 
in 8 bytes. 


Address of the first byte of 
str stored in 4 bytes. 


Address of K stored 
in 4 bytes. 


Value of J (42) stored 
in 4 bytes. 


Value of I (15) stored 
in 4 bytes. 


Return address stored 
in 4 bytes. 
top of stack 


ESP= > 





Lower Addresses 
Figure 6-4. Stack After Call in Example E 


Upon return, since it is the responsibility of the calling routine to pop the arguments 
off the stack, the stack pointer in this example should be pointing to the least signif- 
icant byte of I. The return address is popped off by the called routine. 


The function xfune may return a value in register EAX, but in this example it is 


ignored. The function may also return a result by modifying the array str or in the 
variable K. 
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Assembler Routines Called By Other AIX PS/2 Languages 
When writing 80386 Assembler language routines that are to be called by the other 
AIX PS/2 languages, do not interfere with the way the high-level languages use the 
stack, heap, and internal registers of the 80386. See Table 6-3 on page 6-7 for more 
information on linkage conventions. 


In general, an Assembler routine can use the space on the stack below the address 
indicated by the stack pointer at call time. The stack grows toward smaller absolute 
addresses, so address space with smaller addresses than that in register ESP can be 
used for working memory. 


Using VS Pascal Def/Ref Variables 


In addition to passing data through parameter lists, VS Pascal def and ref variables 
may be used to communicate between Pascal and FORTRAN or C. The def or ref 
variable is associated with a FORTRAN common block name, or a C extern vari- 
able name. 


Note: Only the first eight characters in the def/ref name are significant. 

For communication between Pascal and FORTRAN, the name of the common 
block must be exactly the same as the def/ref variable name. For communication 
between Pascal and C, the name of the C extern variable must be the same as the 
def/ref variable with an underscore (__ ) both prepended and appended to it. 


For example: 


Pascal definition 


def abc: integer; 


FORTRAN declaration 
COMMON /ABC/ A 


C declaration 


extern int _abc_; 
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This chapter describes the conditions, rules, and conventions that the user or pro- 
grammer must observe when mixing program elements of two or more AIX RT PC 
high-level languages. Detailed information is provided for the VS FORTRAN, VS 
Pascal and C Compilers on the RT PC. 


Mixing Languages on RT PC 


The RT PC language system permits the mixing of elements from different languages 
in a single program. This chapter assumes you are familiar with the languages you 
want to mix; the elements of the languages are not described here in detail. 
Appendix C, “Program Examples for Mixing Languages” on page C-1 gives sample 
programs that show how to pass parameters between different languages. 


Correspondence of Data Types 


The data types of one language are usually quite different from the data types of 
another language. Also, the way data is stored is not the same across languages; the 
internal data representation is left unspecified and usually varies with the implemen- 
tation. 


However, a certain amount of similarity among the data types of the different lan- 
guages exists since the languages share many system primitives and since IEEE! 
standard data representations are used as much as possible. Table 7-1 shows some 
of the correspondence among languages. 


Note: Table 7-1 shows how the languages represent data internally in the comput- 
er’s memory rather than how data are passed between program units. 


Table 7-1. Correspondences of Data Types Among Languages 


FORTRAN FORTRAN 
IBM and R1 Modes VX Mode 


Pascal 


Logical*1 Logical*1 Boolean 







Logical*2 


Logical, 
Logical*4 


Logical 
Logical*4 






Integer* 1 Integer* 1 packed/unpacked 
Byte CHAR element 


short 


float 


Integer*2 Integer*2 


Integer*4 | Integer*4 Integer 


Real, Real, Shortreal 
Real*4 Real*4 


Real*8 Real*8 


Foitie | 


int 
packed array char 
of Char 


STRING 


Real 


Double Precision 
Complex 


Complex 






Complex*8 Complex*8 


Complex* 16 Complex*16 


Character Character 


| TEEE 754 Floating-Point Standard. 
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As Table 7-1 shows, each language has data types that do not exist in the other lan- 
guages. When you interface languages, make sure you either avoid mismatching 
data types or use the mismatches very cautiously. When data types do correspond, 
the interfacing of the languages is very straightforward. 


Most numeric data types have counterparts across the languages. However, char- 
acter and string data types do not. The most difficult aspect of language interfacing 
is the passing of character, string, or text variables between languages. 


Character Variables 


FORTRAN’s only character variable type is Character, which is stored as a set of 
contiguous bytes, one character per byte. The length of a FORTRAN character var- 
iable or character array element is determined at compile time and is, therefore, 
static. Character lengths are returned by the FORTRAN intrinsic function LEN. 


Pascal’s character variable data types are String and packed array of Char. The 
String data type has a 4-byte word-aligned string length followed by a set of contig- 
uous bytes, one character per byte. The dynamic length of the string can be deter- 
mined using the length function. The data type packed array of Char, however, like 
the Character type in FORTRAN, is stored as a set of contiguous bytes, one char- 
acter per byte. 


C character data is typically stored as arrays of type char. The char data type stores 
one character per byte; therefore, an array of char is stored exactly like a 
FORTRAN Character variable or a Pascal packed array of Char. 


Storage of Matrices 


FORTRAN matrices are stored in computer memory by column (column major 
order); therefore, the first subscript in a multi-dimensional array varies fastest. An 
array dimensioned as: 


A(3,2) 
is stored in this order: 
A(1,1) A(2,1) A(3,1) A(1,2) A(2,2) A(3,2) 
Pascal and C matrices are stored in computer memory by row (row major order). 
For example, an array in Pascal declared as: 
A: array [1..3,1..2] of Real 
is stored in this order: 
AL1,1] AL1,2] A[2,1] A[2,2] A[3,1] A[3,2] 
Since the matrix storage convention for Pascal and C differs from that for 


FORTRAN, be careful when passing references to matrices between FORTRAN 
and the other languages. 
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Input/Output Primitives 


Primitive input/output routines are usually bound to a user’s program during the 
final linking process when the AIX linker includes the necessary code from the lan- 
guage run-time library (libvsfor.a for FORTRAN), and the system run-time library 
(libvssys.a for FORTRAN and Pascal). 


When you mix, for example, FORTRAN and Pascal, you must remember to link 
both libvsfor.a and libvssys.a in this order. This allows the primitives needed for 
both the FORTRAN and Pascal parts of the program to be present. 


The input/output primitives are different for each language; because of this you are 
not able, for example, to open a file or device for use by one language and write to 
it or read from it in a different language. Generally, however, two languages can 
exist in a program as long as they each have their own files and device for 
input/output, which includes the console device. | 


When the main program is not compiled using the RT PC C compiler, special han- 
dling is required when calling RT PC VS Pascal and RT VS FORTRAN subroutines 
that perform input/output or floating-point arithmetic. 


An initialization routine must first be called from the main program so that the 
floating-point arithmetic entry points and the input/output buffers and information 
are properly set up: for RT PC VS Pascal, the routine is vspio and is in the system 
run-time library libvssys.a; for RT PC VS FORTRAN, the routine is vsfio and is in 
_. the language run-time library libvsfor.a. These routines do not require parameters. 


Note: :When using RT PC FORTRAN languages, a trailing underscore is automat- 
ically appended to the routine name; therefore the duplicate routines vspio_ and 
vsfio_ are included in the libraries. When calling VS FORTRAN from a non-RT VS 
Main program, you should include a call to vsfio_ as standard practice. 


To properly flush input/output buffers before program termination from a main 
program that has called a FORTRAN subroutine, the routine vstfio_ must be called 
immediately before exiting your main program. 


Whenever you mix languages, you need first to become familiar with the require- 
ments of each particular subroutine and each language’s argument-passing require- 
ments. 


Subroutine Linkage Convention on RT PC 


The subroutine linkage convention describes the machine state at subroutine entry 
and exit. This scheme allows routines that are compiled separately in the same or a 
different RT PC language to be linked and executed when called. 


Load Module Format 
The load module format used is AIX GPOFF (General Purpose Output File 
Format). For the GPOFF, each routine has a constant pool in the data segment. A 
constant pool is a data area created for each routine. The first word of each rou- 
tine’s constant pool contains the address of the routine’s entry point. A constant 
pool also provides the routine with addressability to constants, local data, and any 
called-routine’s constant pool. A constant pool pointer (cpp) is passed in register 0 
on a call. 
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Register Usage 


If a register is not saved during the call, its contents may be changed during the call. 
Conversely, if a register is saved, its contents are not changed, and the register can 
be used as scratch (that is, as a work area). Table 7-2 lists registers and their func- 
tions. 


Table 7-2. Register Usage 






Register 








Constant pool pointer. On call, contains address of 
called routine’s constant pool. Can also be used for 
scratch between calls. 








On call, first word of parameter words to called 
routines. On return, first word of return value. 
Between calls, can be used as scratch. 





On call, second word of parameter words to called 
routines. On return, second word of return value 

(for example, low-order 2 words of a floating-point 
value). Between calls, can be used as scratch. 


no On call, third word of parameter words to called 
routines. Between calls, can be used as scratch. 


Not involved in call interface. Can contain register 
variables or can be used as scratch. 
- Not involved in call interface. Can contain register 


variables or can be used as scratch. 


yes Not involved in call interface. Can contain register 
variables or can be used as scratch. 


Not involved in call interface. Can contain register 
variables or can be used as scratch. 


Not involved in call interface. Can contain register 
variables or can be used as scratch. 
— a Not involved in call interface. Can contain register 





oun) 


no On call, fourth word of parameter words to called 
routines. Between calls, can be used as scratch. 


variables or can be used as scratch. 


NO 


Not involved in call interface. Can contain register 
variables or can be used as scratch. 


WW 


Not involved in cajl interface. By convention, 
however, contains address of current routine’s con- 
stant pool. 
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Stack Frame 


When a routine is called, the compiler passes parameter words 5 through nv on the 
stack. Space is allocated for parameter words 1 through 4. If the routine uses local 
or temporary variables, they are allocated space on the stack. The stack grows from 
higher addresses to lower addresses. A single frame-pointer register (register 13) is 
used to address local storage, incoming and outgoing parameters, and the save area. 


HIGH ADDRESSES 


Caller's 
Stack 
Area 
Input 
Parameter +— Caller's Stack Pointer 
Words (Register 1) 
Linkage Area 
Register 
Save 
Area 
| <«—— Frame Pointer 
(Register 13) 
Output 
Parameter +— Current Stack Pointer 
Words (Register 1) 





LOW ADDRESSES 


Figure 7-1. Contents of a Stack Frame 


Figure 7-1 represents the contents of a stack frame. The areas in the stack are 
described as follows: 


e Input parameter words 

e Linkage area 

e Register save area 

e Local and temporary stack area 
¢ Frame pointer 

¢ Output parameter words 

e Total stack frame. 
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Input Parameter Words: Ifa routine receives more than 4 parameter words, upon 
entry the stack pointer (register 1) addresses the locations in the stack where param- 
eter words 5 through n are stored. Immediately below the stack pointer is a 4-word 
area in which the first 4 parameter words (passed in registers 2 through 5) can be 
stored by the compiler. The parameter words are stored only if registers 2 through 5 
are to be used as scratch registers or if a parameter address is required. This area is 
present regardless of the number of parameters being passed. 


regparsize = 16 # Size of area in which first 4 
# parameter words can be stored. 


Linkage Area: The first word of the linkage area is reserved for storing the environ- 
ment pointer, which is the frame pointer (register 13) of the routine in which the 
current routine is nested. It is used to gain addressability to the enclosing routine’s 
local variables. Internal calls to nested routines do not use this pointer. It is 
required to support Pascal parametric procedures or functions since they may be 
called from a separately compiled routine. 


envirsize = 4 # Environment pointer size 


The next 4 words of the linkage area are reserved. 


resrvsize = 16 # Reserved area size 
linksize = envirsize + # Link area size 
resrvsize 


Register Save Area: The general-purpose registers (GPRs) and floating-point regis- 
ters (FPRs) are saved in the register save area. GPR 15 is always saved in the 
highest word of the register save area. Floating-point registers are saved imme- 
diately following the GPRs. 


Rn # First GPR saved (6 <= Rn <= 15) 

GPRsize = 4*(16-Rn) # GPR save area size 

Save = regargsize + # Offset of GPR save area 
linksize + GRPsize 

FPRsize = 4*163 # FPR save area size 

savesize = GRPsize + # Total register save area 
FPRsize 


Local and Temporary Stack Area: When a routine needs space for local or tempo- 
rary variables, the compiler allocates space for them in the local and temporary stack 
area. The size of this area is known at compile time. 


set localsize # Size of local auto's and temp's 


Frame Pointer: The compiler uses register 13 as the frame pointer to address 
sections in the stack frame. The register save area, linkage area, and input param- 
eter words are referenced as positive offsets to register 13. The local and temporary 
variables are referenced as negative offsets to register 13. Output parameter words 
are referenced using register 1, the current stack pointer. 


Output Parameter Words: If a routine makes a call with more than 4 parameter 
words, the compiler allocates space for the parameter extension list immediately 
above the stack pointer. This area is large enough to hold the biggest parameter 
extension list for any call made by the routine. 


extlistsize # Size of biggest parameter extension list 
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Total Stack Frame: The entire stack frame can be thought of as including all the 
space between the caller’s stack pointer and the current stack pointer. It is also rea- 
sonable to consider the input parameter area as being part of the current stack 
frame. In a sense, each parameter area belongs to both the caller’s stack frame and 
the current stack frame. In either case, the stack frame size is best defined as the 
difference between the caller’s stack pointer and the current stack pointer. 


framesize = regargsize + # stack frame size 
linksize + savesize + 
localsize + extlistsize 


Parameter Passing 


Function Values 


The contents of the parameter words vary among languages. Parameters are under- 
stood to occupy an array in the stack, with each parameter aligned on a word 
boundary. The compiler allocates space in the stack for all the parameter words, but 
it does not store the first 4 words on the stack. These values are passed in registers 2 
through 5. They are only copied to the stack space if a parameter address 1s 
required or if registers 2 through 5 are to be used as scratch registers. Parameter 
values are passed according to type: 


e A type value less than or equal to 4 bytes is passed night-justified in a single 
word or register, word aligned. 


¢ In RT PC VS Pascal and FORTRAN, a parameter that is a procedure or func- 
tion is passed as a pointer to the routine’s constant pool. In addition, for RT 
PC VS Pascal, the routine’s environment pointer is passed in the next successive 
word. 


e A double value is passed in two successive words, which need not be doubleword 
aligned. One may be in register 5 and the other 1n the stack frame. 


Functions return their values according to type: 
e A type value less than or equal to 4 bytes is returned right-justified in register 2. 


e A double value is returned in registers 2 and 3. 


Parameter Addressing 


Traceback 


The input parameter words 5 through n can be addressed in the stack by: 


linksize + savesizet+4*k-4(r13) | # get k-th parameter word 


If the compiler stored the first 4 parameter words (registers 2 through 5) in the stack 
frame, then they can be addressed the same way. 


The compiler supports the traceback mechanism, which is required by the AIX Oper- 
ating System Symbolic Debugger in order to unravel the call/return stack. Each 
module has a traceback table 1n the text segment at the end of its code. This table 
contains information about the module including the type of module as well as stack 


- frame and register information. 
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Entry and Exit Code 
The compiler adds entry and exit code around each routine’s code, which sets up and 
removes the routine’s stack frame. 


The entry code: 


¢ Saves modified non-volatile registers 

e Decreases stack pointer (register 1) by framesize 

¢ Copies the constant pool pointer from register 0 to register 14 

e Sets frame pointer (register 13); if the routine is the main program, register 13 
points to the global data area. 


The exit code: 


¢ Restores stack pointer (register 1) 
e Restores registers. 


Calling a Routine 
A routine has two symbols associated with it: a constant pool pointer (_name) and 
an entry point (.name). When a call is made to a routine, the compiler branches to 
the .name entry point directly and loads the _name constant pool pointer into reg- 
ister 0. If the routine entry point is not within a megabyte of the call, the compiler 
loads the _name constant pool pointer, loads the .name entry point from the first 
word of the constant pool, and branches to it. 


Using VS Pascal Def/Ref Variables 


In addition to passing data through parameter lists, VS Pascal def and ref variables 
may be used to communicate between Pascal and FORTRAN or C. The def or ref 
variable is associated with a FORTRAN common block name, or a C extern variable 
name. 


Note: Only the first eight characters in the def/ref name are significant. 

For communication between Pascal and FORTRAN, the name of the def/ref vari- 
able is the same as the common block but with an underscore appended to it. For 
communication between Pascal and C, the name of the def/ref variable must have an 


underscore appended to it. The C extern name must be the same as the def/ref 
name, including having the underscore ( __ ) appended to it. 


For example: 


Pascal definition 


def abc_: integer 


FORTRAN declaration 
COMMON /ABC/ A 


C declaration 


extern int abc ; 
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This chapter specifies AIX/370 conventions for inter-procedural calls. Specifically, 
these include: 


Stack frame layout 

Register usage during call, prolog, and epilogue 
Argument and result passing 

Trace table definition. 


Also discussed are object code attributes required to support debuggers and other 
routines which perform trace-back. 


The first section, “Linkage Specifications” on page 8-2, provides the formal defi- 


nition. Subsequent sections give examples of usage. Debugger considerations (for 
example, trace back) are discussed in “Trace Back Implications” on page 8-11. 
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Linkage Specifications 


Stack-based 


Call Linkage 


Register Volatility 


Argument Passing 


R13 always identifies the beginning (lowest address) of the current stack frame. 


Negative growing — AIX/370 establishes a write/protected red-zone page imme- 
diately below the lowest address allocated for stack usage. In the typical 
linkage,! this avoids explicit stack overflow checking in each procedure prolog. 
Instead, the kernel can automatically expand the stack size when an attempt to 
store is detected for an address below R13 and above the lowest address cur- 
rently allocated to the stack. 


88-byte, doubleword-aligned stack frame header (see “Stack Frame Header” on 
page 8-3 for a definition). 


4(R13) is used to store (and hence identify) the address of the calling procedure’s 
stack frame. Frameless routine detection is discussed in “Trace Back 
Implications” on page 8-11. 


R14 defines the return address. 
R15 defines the called routine’s entry point address. 


Proper handling of these registers in procedure prolog/epilogue sequences is critical 
for trace back operation. See “Trace Back Implications” on page 8-11 for details. 


R2—R12 must be saved and restored if modified by a program. 
RO and the FPRs are scratch unless required for a return value. 
R1 is always scratch. 

Restoration of R13 is implicit in its role as the stack pointer. 


R14 and R15 must be preserved in accordance with trace back requirements in 
“Trace Back Implications” on page 8-11. 


The argument list occupies successive fullwords in the caller’s stack frame imme- 
diately following the caller’s register save area for R15. 


e The first four words are passed in registers RO-R3 and thus an initial STM such 


as: STM R4, R3, 24 (R13) could be used to save these values, if required, in 
their respective reserved locations in the argument list. 


An argument of less than four bytes is right-aligned in its word. An argument 
of more than 4 bytes (for example, a structure) is left-aligned in multiple words. 


Procedures which return a structure or union are passed a pointer to the return 
area as a hidden first argument in RO. 


1 Where the stack frame size is < bytes. 
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Return Value 
e Simple values are returned via RO (integer, character, pointer) or FPRO-62 for 
floating point values. 


e Structures and unions are moved by the called procedure to the area specified by 
the hidden first parameter. 


Trace Back 
Trace back methodology is discussed in “Trace Back Implications” on page 8-11. 
Each entry point 1s preceded by a trace table in one of the formats described in 
“Trace Table” on page 8-4. 


Special Considerations 
These are special situations which a compiler may choose to be aware of in support 
of optimization or support of run-time services. 


Frameless routines are any routines that do not call another procedure, have a 
limited requirement for local storage, and do not acquire a stack frame. 


Standard Service Routines 
Several service routines are required in support of this linkage specification. While 
the service routines themselves are not a proper part of this specification, certain 
aspects of their behavior are assumed in order to assure efficient linkages. Addi- 
tionally, the existence of a StackCheck routine is dictated by this specification. See 
“Service Routines” on page 8-10 for additional information of StackCheck, alloca() 
and mcount. 


Stack Frame Header 
The following structure defines the fields in the stack frame header. Field names are 
used illustratively and are not intended to be a standard nor is anything implied by 


conflict between the names here and other names within the AIX/370 system’s source 
files. 


Struct stackframe { 
unsigned long sf_lang_word; /* A language specific word 
reserved for usage such as 
the Pascal static link */ 


struct stackframe *sf_of_caller; /* back chain to caller's 
stack frame a) 

unsigned long sf_reserved[2]; /*reserved af 

unsigned long sf_save 2 15[14] /*R2-R15 save area =) 


2 The number of FPRs (Floating-Point Registers) required to contain the return value will be utilized. 
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Trace Table 


/* Argument list begins here -- the first two words 
coincide with RO-R3 save areas. 


unsigned long sf_r0_pl; /* RO save area / Parameter word 1 */ 
unsigned long sf_rl_p2; /* Rl save area / Parameter word 2 */ 
unsigned long sf_r2_p3; /* Reserved for Parameter word 3 */ 
unsigned long sf_r3_p4; /* Reserved for Parameter word 4 */ 
unsigned long sf_parm_5; /* Parameter word 5 */ 


. additional parameters follow here 


: 


Note: Additional parameters words beyond the first four are passed to the called 
procedure in memory immediately following sf_r3_p4. 


Each procedure has a trace table immediately before its entry point. Trace tables are 
utilized by debuggers to assist with failure analysis. They provide such information 
about the number of inbound parameters, the maximum number of outbound 
parameters, assignment of arguments to registers or storage during execution of the 
procedure, and the size of the code associated with the procedure. Trace table 
content is extensible in that a format field identifies the particular trace table struc- 
ture. C structures follow describing three currently defined trace table formats. 


Format 1: This is the standard trace table format providing the information 
required by the debuggers for normal routines. 


struct tracetable fl { /* Format 1 trace table ie 
unsigned short t_arglength; /* WORDs of memory required for the 
longest outbound parameter list 

beyond the minimum four allowed 
for in the register save are. */ 

unsigned short t_argl:4, /* If a sub-field # 15, then the 


t_arg2:4, corresponding parameter is saved 
t_arg3:4, in the memory argument list area, 
t_arg4:4; otherwise it defines the register 


allocated to the argument within 
this procedure. */ 
unsigned long t_codesize; /* size of procedure code */ 
unsigned short t_flags; /* See text notes */ 
unsigned char t_parmlength; /* Number of arguments words declared 
by this procedure including the 
initial 1-4 passed in registers */ 
unsigned char t_format; /* =1... a format 1 trace table */ 


ie 
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Format 2: This trace table format provides the absolute minimum and may only be 
used for frameless routines. 


struct tracetable f2 { /* Format 2 trace table =] 
unsigned char t_parmlength; 
unsigned char t_format; /* =2 ... a format 2 trace table */ 
bs 


Format 3: This alternative format provides for procedures which require an undeter- 
mined amount of arbitrary data associated with an entry point. The tagged data 
consists of a sequence of arbitrary self-describing entries. 


struct tracetable f3 { /* Format 3 trace table a 
Struct tagdata *t_tagdata; /* Address of the tagged data area.*/ 
unsigned short t_arglength; 
unsigned short t_argl:4, 
t_arg2:4, 
t_arg3:4, 
t_arg4:4; 
unsigned long t_codesize; /* size of procedure code */ 
unsigned short t_flags; 
unsigned char t_parmlength; 
unsigned char t_format; /* =3 ... a format 3 trace table */ 


s 
The tagdata structure is described under “Tagged Data” on page 8-13. 


Format 0: This trace table format is obsolete but may exist in binary files. 


struct tracetable fO { /* Format @ trace table ay 

unsigned short t_arglength; 

unsigned short t_argl:4, 
t_arg2:4, 
t_arg3:4, 
t_arg4:4; 

unsigned char t_parmlength; 

unsigned char t_format; /* =0... a format 0 trace table */ 

ie 
Notes: 
1. The t_format field is immediately followed by the entry point. 


2. If a trace table requires padding for alignment, the padding should precede the 
trace table. 


3. The root (actually the end, memory address wise) section of the trace table is 
common to all formats. 


4. t_flags is reserved to store trace table modifiers and/or additional information 
about the annotated entry point. 


Summary of Linkage Characteristics 
¢ Call: 2 instructions (6 bytes plus adcon) 
¢ Prologue: 54 instructions (16 bytes plus constant) typically 
e Epilogue: 2 instructions (6 bytes) 


¢ No limitation on size of program, stack frame, or argument list 
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Reg 


WO cn DO WM KF © 


Parameter passing: first four words passed in registers 

(Code base register usage is not in the domain of linkage conventions.) 
Varargs supported 

alloca() supported 


In a typical stack frame of < bytes, a single stack pointer can address outgoing 
arguments, local variables, the register save area, and incoming arguments. 


The stack frame header provides a back chain pointer for locating the previous 
stack frame as well as a register save area, argument storage, etc. 


A trace table before entry point gives information for debuggers 
Linkage designed for use by C, Pascal, and FORTRAN 


Frameless routines may utilize as scratch storage any word in the basic stack 
frame header (other than the back chain pointer) that is not required for pre- 
serving the caller’s registers. 


AIX/370 Linkage 
Register Conventions 


Life Use 


Killed Parm 1 and simple return value 
Killed Parm 2 

Saved Parm 3 

Saved Parm 4 

Saved 

Saved 

Saved 

Saved 

Saved 

Saved 

Saved 

Saved 

Saved 

Saved Stack Pointer 

Saved Ret: Return Address 

Killed Sbr: Called Procedure Entry Point 


Killed Float or double Return Value 


Killed (return value if complex or extended precision) 
Killed (return value if complex extended precision) 
Killed (return value if complex extended precision) 


Explanatory notes 


Simple results (char, int, pointer) are returned in RO. 
Floating results are returned in f0 (and f2-f6 if required). 


Program base register allocation? is a responsibility of each compiler and is 
therefore not included in this specification. 


The stack pointer points to the bottom of the stack. 


3 Note that code chunking can be exploited to avoid the need for multiple base registers for large program code. 
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Linkage Examples 


This section is intended to clarify the linkage conventions by illustrating how a com- 
piler or assemble language programmer might code the various epilogue/prolog and 
call linkage sequences required by the convention. 


Registers shown by register number (for example, R13) are specific registers required 
by the linkage convention. Registers required to accomplish a particular code frag- 
ment will be shown as a non-numeric register (for example, Ra, Rb, Rtemp). 


This figure shows the stack just before execution of a called procedure’s prolog. 


Register 
Save 

area 

to be STM'd 


by callee 


Stack pointer 
r13 


Run-time Stack 
AIX/370 Linkage 


Caller's 


local 
variables 


Pn 
(88) P5 
r3 = P4 
r2 = P3 
rl = P2 
r0 = Pl 
r15 
r14 
r13 
r12 


rll 
r10 


(16) 2 


(reserved 
words) 
(4) back chain > 


(0) language word 


To be 
callee's 
local 
variables 
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High addresses 


back pointer 


end of maximum length arglist: 
Caller saves these before call. 


Fixed-size area: 


callee STM's rO0-r3 only if 
necessary (e.g., for varargs) 

Start of arg list 

Callee's entry address 

Caller's return address 

Caller's frame bottom 


r2-r12 STM'd only if necessary 


Two words reserved for future 
considerations. 


points to previous stack frame 


for example, Pascal static link 


Low addresses 
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Calling Procedure’s Call Code 


The caller passes the first four argument-list words in RO-R3. For longer argument 
lists, the caller stores words 5-n in sequential word-aligned stack locations, beginning 
at 88(R13). A C function returning a struct or union is passed (as a hidden first 
argument) the address of the area to store the result. 


The caller of a nested Pascal procedure stores a static link (the frame pointer to the 
callee’s parent) at 0(R13). 


Once the parameters are in place, the caller invokes the callee with the following 
instructions. 


L r15,=A(callee) 
BALR rl4,r15 


Called Procedure’s Prologue Code 


The entry point is preceded by a trace table holding information for debuggers and 
execution profiling. The trace table format is described in “Trace Table” on 
page 8-4. 


The first instructions store any registers that must be saved (for example, the return 
address, the old stack pointer, and any of the R2-R12 that are needed for scratch 
registers). A local code base is established (if required), the stack pointer is adjusted, 
and the back chain stored. 


Small Size (<4K) Frame 


Callee: 


STM = Ra, Rz(a-z) *44+16(R13) The Ra-Rz range utilized will be a 
compiler optimization issue. R14 
and R15 must be saved. 

LR Rtemp,R13 Copy the in-bound stack pointer. 
Rtemp would typically be the local 
base chosen by the compiler if 


required. 
LR Rcode,R15 The code base register is set 
SL R13 ,=F'framesize' Decrement the stack pointer 
ST Rtemp, 4(R13) Establish the back chain 


Note: framesize must be a multiple of 8. 


The following example illustrates an alternative prolog which makes potentially 
useful trade-offs in register usage, instruction counts, and memory references. 


STM Ra, Rz, (a=2) *4+16(R13) 


LR Rtemp,R13 Copy old stack frame 
LA Rcode, framesize Trade LA and SLR for SL with 
SLR  R13,Rcode memory reference constant 


ST Rtemp,4(R13) 
LR Rcode,R15 


Large Size (> 4K) Frame 


The above code assumes a stack frame smaller than the red-zone size. If framesize 1s 
larger than 4096 bytes, the following prolog might be used. A minimal (88 byte) 
stack frame is established and then StackCheck is called to verify that sufficient 
memory exists to hold the required stack frame. StackCheck returns with R13 prop- 
erly adjusted to reflect the full size stack frame. 
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Execution Profiling 


vararg Support 


Epilogue Code 


Callee: 
STM Ra, Rz, (a=2) *4+16(R13) (See comments above re. Ra, Rz) 


LR Rtemp,R13 Save the in-bound stack pointer 
LA Rcode, 88 Establish a minimum stack frame 
SLR R13,Rcode nrg 

ST Rtemp,4(R13) minimum stack frame completed 
LR Rcode,R15 | Set code base register 

L R15,=A(stackCheck) To the checker routine 

BALR R14,R15 

DC AL4(framesize=88) size of desired frame expansion 


The choice of registers for addressing locations in the stack frame is a compiler deci- 
sion. R13 always addresses the start of the stack frame; another register may be 
needed to address the end of the frame if the frame is large or the value of R13 will 
be changed by calls to alloc(). 


When profiling is enabled, the following code segment is added to the end of the 
prolog. mcountword is the address of a fullword allocated by the compiler in the 
data segment. Each procedure profiled has a unique mcountword. 


L R15,=A(mcount) profiling routine 
BALR R14,R15 
DC AL4(mcountword) 


The mcount procedure must be written to preserve al/ registers. 


If the called procedure takes the address of any argument name, the compiler must 
ensure that argument list words 1, 2, 3, and 4 reside in memory in their proper posi- 
tions.4 


An integer result is returned in RO; a floating result in FO(=F6 if required). A 
multi-word result (for example, a C struct or union) is returned by having the callee 
move it to the caller’s storage. The caller passed the address of this area as a hidden 
first argument. The epilogue code restores any modified registers in the range 
R2-R14. 


The first example illustrates the typical epilogue sequence applied when the stack 
frame is < 4K bytes in size. A similar optimization is possible if the compiler has 
allocated a register which would provide basing for the inbound stack frame header. 


LM Ra,R14, (a=2)*4+16+framesize(R13) 
BR R14 


4 The varargs macros declare 4 arguments so that all four parameter registers are saved. 
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The next example illustrates the general case where basing for the caller’s stack 
frame must be established by the epilogue: 


L Rtemp,4(R13) Use of Rtemp avoids an 
ambiguous state for R13 

LM Ra,R14, (a=2)*4+16(Rtemp) R15 is restored to insure that 
frameless routine ambiguity 
resolution logic will work 

BR R14 


Service Routines 


These routines are not a proper part of a linkage specification, but the functions 
provided are required. The approaches described here for implementation of these 
functions serve to illustrate the limitations and requirements for inclusion of similar 
function. A compiler is likely to desire special knowledge of the existence of these 
routines or actually require the routine for mandatory services. 


These routines all receive a compiler furnished special parameter coded as a full 
word unaligned constant following the BALr instruction. 
_ StackCheck A routine utilized to allocate stack frames which exceed 4K bytes. 


Prior to calling StackCheck, a standard minimum stack frame (88 
bytes) must be allocated. 


The special parameter passed following the BALr instruction will be 
the required increase in stack frame size. 


The requested size is rounded up to an integral number of 
doublewords and checked to insure that the resulting stack frame 
pointer will remain within bounds. 


The new stack frame header is established and initialized as follows: 
1. The 4(r13) value inbound is loaded into Rtemp. 
2. R13 is set to its new value. 


3. ST Rtemp,4(R13) establishes the back-chain, language word and 
reserved words. StackCheck now appears as frameless routine 
without a stack frame. 


4, Control transfers back to the caller. 


alloca A special memory allocate interface for expansion of the stack frame. 
alloca allocates space within the stack frame by decreasing R13, 
checking for stack overflow, and returning a pointer to the area 
immediately following the outgoing argument list. Processing is 
similar to StackCheck except: 


1. The special calling sequence parameter specifies the size of the 
actual stack frame header and maximum outbound argument list 
utilized by the calling routine. 


2. The size request is passed as parameter | (RO). 


3. The allocated memory address is the return value (in RO). 


5 Programs which utilize this routine may not depend upon R13 for access to local variables. 
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mcount Used by a compiler to generate linkages to a standard routine for col- 


lection of execution profile information. The special parameter will 
contain the address of a fullword allocated and initialized to zero by 
the compiler in the data section of the program. 


Debugger Considerations 


Trace Back Implications 


Assumptions 


Methodology 


. A frameless procedure does not establish its own stack frame. 
. Each entry point has an associated trace table. 


. An ambiguous state procedure is any procedure which currently does not own a 


stack frame (for example., during prolog/epilogue processing). 


. R14 and R15 must be saved by non-frameless procedures. 


. R14 reflects the procedure return value for all frameless and ambiguous state 


procedures. 


. The two instruction sequence required to push® the stack are adjacent. 


. If a frameless procedure saves R14, it also stores R15. 


This specification includes the requirements necessary to provide procedure call trace 
back. This chapter discusses how those requirements might be translated into accu- 
rate trace back information, even in those narrow windows between the two 
instructions required to push the stack or pop and return from a procedure. 


e The stack push operation is interpreted as an atomic operation by the debugger. 


If the next instruction to be executed is a ST Rtemp,4(R13) instruction then the 
trace back routine will use the actual contents of Rtemp’ rather than the value at 
4(R13) as the back chain pointer required to establish the address of the calling 
procedure’s stack frame. 


The interval in each routine’s prolog between the STM Ra,Rb,xxx(R13) and the 
ST Rtemp,4(,R13) instruction which establishes the calling procedure’s stack 
frame pointer as well as any frameless routines which do not allocate a stack 
frame present an ambiguous situation. That ambiguity may be resolved by 
which ever of the following techniques is applicable: 


1. Object file includes the symbol table: 


The symbol table is used to relate the PSW address to the routine in 
control. 


6 R13 must be decremented by the size of the stack frame and the previous stack frame pointer must be stored in the 


new stack frame header. 


7 Violation of the requirement that the decrement of R13 be immediately followed by establishment of the back chain 
will almost certainly result in a faulty back trace in the event of an asynchronous interrupt before the back chain is 


valid. 
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2. Object file does not include the symbol table: 


a. The back chain pointer is used to identify the previous stack frame 


entry’s R15 (and hence entry point of the called procedure associated 
with that stack frame entry). 


. The previous trace table is located using the previous R15. 


. If the current PSW is not between the previous R15 and the end of that 


procedure’s code as determined from the trace table and the current R14 
is within that procedure’s code space, then it is assumed that a proce- 
dure which has not allocated or will not allocate a stack frame is cur- 
rently in control: 


— Any registers saved by the current routine may be found in the stack 
frame header identified by R13. 


— An attempt will be made to locate the actual inbound registers asso- 
ciated with a frameless routine as follows: 


1) If the next instruction is an STM from R13 at the proper stack 
frame header locations for the register being stored and R15 
also contains the next instruction address, then a debugger will 
assume the current register contents are the inbound values. 


2) If the value of R14 matches the appropriate register save area 
location, then the R15 save area value will be used. If an STM 
exists at that location, it will be assumed to define the set of 
registers stored for this procedure. 


3) If the current contents of R15 point to an appropriately struc- 
tured STM off of R13, then that STM will be assumed to define 
the inbound register save set. 


If this process is not successful, then the debugger will report the 
contents of the R13 identified stack frame register save area. 


d. Otherwise, the save area in the current stack frame header will be 


reported as inactive as it has been determined that the ambiguous situ- 
ation does not exist and the back chain pointer properly identifies the 
parent of the executing procedure. 


All procedures provided with AIX/370 are expected to conform to these specifica- 
tions. A nonconforming routine may result in an ambiguous or invalid trace back. 
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Tagged Data 


Tagged data provides for inclusion of arbitrary information associated with an entry 
point which is guaranteed to be memory resident. The self-descriptive format pro- 
vides for future extensibility. 


struct tagdata { 
unsigned char td_typecode; /* type code 
0x00 = End marker 
0x01 = Entry point name 
0x02 = Copyright 
0x03 = Program version - includes 
the following possible 
tagged sub-fields: 
0x00 (optional end) 
Ox01 - Product ID 
Qx02 - Source date/time 
0x03 - Structured Version 
0x04 - unstructured version. 
OxFF = Escape to alternate format 
allowing longer code and 
length fields. 
unsigned char td_length; /* bytes of data in tagged data */ 
unsigned char td_data[l]; /* data */ 


ie 
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This chapter provides sample programs that can be compiled with the C compiler. 
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Prime Example 


This example determines the prime numbers in the range from | to 8190. 


#define TRUE 1 
#define FALSE 0 
#define SIZE 8190 


char flags[SIZE]; 


main() 

i 
Count the primes up to 8190 by marking off multiples 
of primes in succession 

a 

{ 


int i, k, count; 
count =0; 


/* 0 and 1 are not primes */ 
for (i=2; i < SIZE; i++) flags[i] = TRUE; 


/* mark multiples of every prime starting with 2 */ 
for (i=2; i < SIZE; i++) 
{ 

/* is i a prime? */ 

if(flags[i]) 

{ 


/* count i as a prime */ 
count+t; 


/* mark every multiple as note a prime */ 
for(k=i; k<SIZE;k+=i) flags[k] = FALSE; 


#ifdef PRINT 
printf ("prime = %d\n",i); 
#endif 
} 


printf("\n%d primes\n", count) ; 
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AIX System Call Example 


This example obtains information about a file. It demonstrates the use of AIX 
system call stat. 


#include <sys/stat.h> 


char *path; 
Struct stat buf; 


main() 

{ 
printf ( "\n_ This program uses the system call: stat\n"); 
printf ( " The call obtains information about a file.\n" ); 
printf ( "0 wen--------- 2-2-2 n-ne \n\n" ); 
path = "/usr/bin/vi"; 
printf ( " Obtaining information on file: %s\n\n",path ); 


if ( stat (path, &buf ) != 0 ) 
printf ( "******** Error in stat\n" ); 


else { 

printf ( " ID of the device that contains a directory" ); 
printf ( " entry for this file: %d\n",buf.st_dev ); 

printf ( "  Inode number: %d\n",buf.st_ino ); 

printf ( " File mode: %d\n",buf.st_mode ); 

printf ( " Number of links: %d\n",buf.st_nlink ); 

printf ( " User ID of the file's owner: %d\n",buf.st_uid ); 
printf ( " Group ID of the file's group: %d\n",buf.st_gid ); 
printf ( " ID of device: %d\n",buf.st_rdev ); 

printf ( " File size in bytes: %d\n",buf.st_size ); 

printf ( " Time of last access: %d\n",buf.st_atime ); 
printf ( " Time of last data modification: " ); 

printf ( "%d\n",buf.st_mtime ); 

printf ( " Time of last file status change: " ); 

printf ( "%d\n\n",buf.st_ctime ); 

} 
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Asm Statement Example for PS/2 and RT PC 


ie 
This is an example of the asm statement on the PS/2 and RT PC. 
It is used to see if an overflow occurs when adding 2 positive 
numbers. 

si 


#include <stdlib.h> 
#include <stdio.h> 


void test_overflow(unsigned int, unsigned int); 
int check_flag(void); 


main(int argc, char *argv[]) 


{ 
unsigned int a,b; 
if (argc != 3) 
printf("ERROR: 2 arguments expected\n"); 
else { 
a = (unsigned) atoi(argv[1]); 
b = (unsigned) atoi(argv[2]); 
test_overflow(a,b); 
exit (0); 
} 
void test_overflow(unsigned int x, unsigned int y) 
{ 
int ret; 
xX + Y3 /* add the 2 numbers */ 
ret = check flag(); /* get carry flag */ 
if (ret & 0x100) /* if carry flag is set */ 
printf("OVERFLOW\n"); /* then overflow occurred */ 
else /* else get result i 
printf("x + y = %u\n", xty); 
} 
int check_flag(void) 
{ 


/* lahf instruction: the flags which indicate an overflow are in 
register EAX, so there is no return statement. */ 
asm(Qx9f) ; 


Asm Statement Example for System/370 


_ASM (" assembler instruction \n"); 
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Appendix A. Messages 


The PS/2 C Compiler contains a file of compile-time error messages named 
/usr/lib/msg/vscctmsg.inc.. The compiler generates English error numbers and mes- 
sages if this file is present on the default directory and errors are encountered. 


The System/370 C Compiler generates the following error messages: 


Error and Warning Messages 
This section presents all compiler diagnostic messages (except automatically gener- 
ated lexical and syntactic messages) in alphabetical order, with explanations where 
appropriate. 


')' missing in macro call. 

#define directive is malformed. 

#else or #elif encountered within a pending #else. 
#pragma statement is malformed. 


'=" encountered where '==' may have been intended. 


= was detected as an operator in a Boolean expression, such as if (x = y) {...}. 
Often this is a mistake, as if (x == y) {...} was intended. 


Anonymous structure member is ambiguous. 
Applying "“offsetof" to a non-struct type. 


Argument name is missing in function declaration. 


For function definitions, argument names must be supplied. For example, void f( 
int, float g) {...} is illegal because the first argument lacks a name. 


Argument name is not specified in function header. 


For function definitions, arguments declared must be present in the function header. 
For example, void f(a,b) int x;..; {...} 1s illegal because x is not present in the function 
header. 


Argument number n not named. 


The nth argument in a named call is not specified. For example, 


int f ( int a, int, int c ) {...} 
f (a=>1,c=>2); 


where the second argument is not specified. 
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Argument of type "void" not permitted. 

Argument of unknown length being passed. 

Argument type not consistent with previous specification. 

Array dimension is negative. 

Array element type is a yet undefined struct/union. 

Array subscript out of range. 

Assignment into a "const" variable is attempted. 

Assignment into a variable of unknown length is attempted. 
Assignment into something of type void is attempted. 

Attempting to apply the function "abs" to an unsigned quantity. 


Attempting to define a variable in data section name that was previously 
defined at Ln/Cn. 


Attempting to take the difference of two pointers pointing to objects of 
unknown length. 


"auto" must appear within a function. "static" assumed. 


Storage class auto cannot be given for declarations that do not appear within a func- 
tion. 


Bad line specifier in #line directive. 
Bit field exceeds word size. 
Bit field is not an integer type. 


Bit field is not valid as an argument to "sizeof". 


Since bit fields need not occupy an integral number of bytes, taking their sizeof is 
prohibited. 


Bit field value expected but encountered '{'. 
"break" statement not within loop or switch. 


Call to a function returning an incomplete or zero-length type 
1s attempted. 


A function cannot return a struct of union type whose fields have not yet been speci- 
fied. For example, struct s; struct s *f() {...} is legal since f returns a pointer 
to an incomplete struct type, but struct s3 struct s g() {...} is illegal. 


Call to non-function is attempted. 


Cannot dereference a pointer to void. 
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Type void* was introduced as a means of defining a “generic pointer” compatible 
with other pointers. But there is no such thing as an object of type void. Therefore, 
dereferencing a pointer to void 1s illegal. 


Cannot dereference pointer; size of object not known. 

Cannot take the address of a register variable. 

Cannot take the address of a struct bit-field. 

"case" encountered outside of a "Switch" statement. 

Constant expression or static address is expected. 

"continue" statement not within loop. 

Data class specifier expected (EXPORT,COMMON, IMPORT). 

Data section class not consistent with previous specification at Ln/Cn. 

"default" encountered outside of a switch statement. 

"default" label previously specified in current switch. 
Dereferencing of a non-pointer is attempted. 


Division by zero is attempted. 


This was detected in a constant expression at compile time. 


Duplicate case label (n); other occurrence at Ln/Cn. 
Duplicate declaration of identifier. 
Duplicate definition of structure member. 


End of file encountered within #if construct (unmatched #if-#else-#elif a 
t Ln/Cn). 


enum tag is not defined. 


A declaration such as enum x; was encountered. Tag x has no definition. 


enum tag previously declared as struct tag. 
enum tag previously declared as union tag. 


Expression has no side-effects. 


An expression used in a statement context has no side effect; therefore the expression 
is useless. For example, 2+ 3;. 


Expression of type "type" should be returned. 
Floating point constant expected. 


Function called but not defined. 
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Any function that was called but not defined is noted as a warning. Although this 
practice is permissible in C and is especially useful when calling library functions, a 
common error is to misspell a function name. Without this warning, the error goes 
undetected until link-time. Further more, errors in parameter linkage can occur 
when a call is made to an undefined function. We recommend that the library .h 
header files always be included to get parameter checking, and that function proto- 
types be used for external function declarations, rather than making use of the 
“feature” of C for calling undefined functions. 


Function declaration is inconsistent with previous declaration at Ln/Cn. 


Function declaration is inconsistent with the “int"-returning function 
declaration imputed at Ln/Cn. 


A function called before it is declared is assumed to be a function returning int, and 
any subsequent declaration of the function must declare it to be so. For example, 
main () { (...) (3); (...) } void f() {...} is illegal since f was called before 
being defined and therefore assumed to return int. 


Function definition semantics overridden by prototype at Ln/Cn. 


A prototyped function declaration takes precedence over an ordinary function defi- 
nition. For example, 


int f ( int a, int b);  /* Prototyped functionality. */ 


int f (a,b) 
int a,b; {...} 


The function declaration in the function definition is overridden by the prototype 
declaration. This warning may be suppressed by turning off the 
Prototype_override warnings toggle. 


Function has no return statement. 


A function with,.a non-void return type contains no return statement. This typically 
happens with “old” C programs that did not use void to indicate that a function 
returns nothing. 


Function name missing. 


Function parameter names are allowed only on function definitions, not 
declarations. 


int f(a,b,c); is a function declaration that names the parameters (a,b,c). This is 
illegal unless function prototype syntax is used, asin int f( int a, int b, int c)s. 


Function specified with more arguments than its declaration allows. 
Identifier expected. 

Identifier is out of context. 

Identifier is undeclared. 

Identifier missing in declaration. 

Identifier missing in struct member declaration. 


Illegal construct within #if expression. 
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Initialization entry is of wrong type. 
Initialization list is longer than aggregate being initialized. 


Initialization of a variable within a "COMMON" or "IMPORT" section is not 
permitted. 


Initializer type does not match type "char". 

Initializing a function is attempted. 

Insufficient number of arguments in pragmas specification. 
Insufficient number of arguments to function. 


Insufficient number of arguments to macro. 


The number of arguments to a macro must agree exactly with the number of param- 
eters in its #define. 


Insufficient number of arguments. 

Integer constant exceeds largest unsigned number. 
Integer constant expected. 

Invalid use of "long" adjective. 

Invalid use of "short" adjective. 

Invalid use of type adjective. 

Label was not defined. 

Label was previously defined at Ln/Cn. 


Left side of '=' is an array, which is not an lvalue. 


In this context a so-called lvalue is required but was not found. An Ivalue is some- 
thing whose address can be taken, and is required on the left side of an assignment 
expression and as an operand to & ++, and --. 


An array is not an example of an Ivalue. 
"long char" treated as "short int". 
"long float" treated as "double". 


Lower bound of range greater than upper bound. 
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This can only happen in C case statements where range expressions are allowed as 
labels (an extension). 


Macro call has too many arguments. 

Macro expansion nested too deeply. 

Malformed conditional compilation control sequence. 

May not cast a nested function to type "type" . 

May not have functions as array elements (but may contain pointers thereto). 
May not return a function from another function (but may return a pointer ther 
May not return an array from a function (but may return a pointer thereto). 
Member not defined in referenced structure. 

Mismatched #if-#elif-#else-#endif. 

Missing macro argument after or before "##" operator. 

Missing macro argument after "#" operator. 

Name is not a member in the applicable structure. 

Name is undefined; "pragmas Alias" ignored. 


Named bit-field of length 0 not permitted. 


A declaration such as struct {int 1:0, j:2 }; was encountered. It must be omitted. As 
is, it is possible to refer to the field. Such a reference would be illegal. 


Nested function may not be assigned into a pointer to a function. 
No "pragmas Data" is active. 
pragma Data; was encountered without a preceding, and matching, pragma 
Data(...)3. 
Not a variable or function; "pragmas Alias" ignored. 
"offsetof" operation cannot be applied to bit field. 
Operand must be of an integer or float type (instead of type). 
Operand of ++ or -- is a pointer to an object of unknown length. 
Operand of the function "abs" must be of arithmetic type. 
Operand of type "type" is not valid for operator operator. 
Operands of type "typel" and/or “type2" are not valid for operator operator. 


Packed structs are not supported; "packed" ignored. 


Packed structs are not supported; status of ALIGN MEMBERS toggle ignored. 


Parameter not found or specified more than once. 
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In a function call using named parameter association, a parameter was named twice, 
or a non-existent parameter was referenced. 


Parameter "name" not supplied. 


Named parameter not specified. For example, 


void P ( int a, int b, float c ) {...} 
P (a=>1, c=> 3); 


does not initialize the named parameter b. 


Passing an argument of type "typel" where "type2" is expected. 


An attempt was made to pass an argument of a wrong type to a function such as 
passing a float for a parameter that is a struct. 


Pointer to an object of unknown length is being indexed. 


Attempting to index a pointer to an object of unknown length. struct x *p; *p[0] 
is an example of this type of error. 


"pragma Code" specified within function definition; ignored. 


"oragma Data" active at end of module. 


A pragma Data (...); was given in a module or function, with no terminating pragma 
Data;. This is permitted but the programmer may have forgot ten to supply the 
terminating pragma, thus perhaps including more data declarations in a data 
segment than intended. 


Previous "pragma Data" is still active. 


pragma Data (...); was given in the context of an already active pragma Data (...). 
Insert pragma Data(); preceding the offending pragma to “turn off” the active 
pragma. 


Previous definition of macro superseded. 


Redefinition of a macro is permitted. The redefined macro takes precedence over 
existing definition of the macro. 


Prototype causes non-standard conversion from "typel" to "“type2". 


The prototype syntax, causes the non-standard conversion from typel to type2. 
This is signaled as a warning to indicate to the user that such a conversion is taking 
place. 


Real constant has too many digits. 
Redundant class specification. 


"register" must appear within a function. "static" assumed. 
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Storage class register cannot be given for declarations that do not appear within a 
function definition. 


Right operand of shift operator exceeds word size (=n). 
Right operand of shift operator is negative. 

Right operand of "%=" operator is zero. 

Section name not specified in "pragma Data"; pragma ignored. 
Selection of a member from a non-structure is attempted. 
"short char" is not supported. 

sizeof being applied to “void" type. 

sizeof being applied to a function type. 

sizeof being applied to an array of unknown length. 


sizeof being applied to incomplete struct/union. 


The sizeof a struct or union type whose fields have not yet been specified is not 
known. For example, struct s; (...) sizeof ( struct s ) (...) is illegal 
because the size of the structure is unknown. 


Specifier "class" ignored; no variable being declared. 


In a declaration such as static struct s {int x;};, the storage class static is useless 
since no object was declared. 


Specifier "Specifier" is not valid for a formal argument. 


Static function is not defined nor referenced. 


A function of storage class static is neither defined nor called anywhere in the com- 
pilation unit. 


Static function is not defined. 


Static function is not referenced. 


A function of storage class static is not called anywhere in the compilation unit. 
Since it is not exported, there can be no reference to the function and it is essentially 
deleted. 


Storage class "class" is not valid for a struct member. 
Storage class "class" cannot be initialized. 

Storage class for function should be static or extern. 
String constant denoting section name expected. 

String exceeds the length of array being initialized. 
String exceeds the length of the array being initialized. 
String expected. 


String truncation required. 
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struct tag was previously declared as a union. 

struct was previously defined as a union. 

struct/union tag was previously declared as an enum. 
struct/union tag was previously declared as an enum. 
Structure has no contents (is of size zero). 

Superfluous "pragma Code" specifiers. 

Superfluous "pragma Data" specifiers. 

Superfluous type qualifier. 

Superfluous type specification. 

switch expression cannot possibly have the value n. 

Switch statement has no cases. 

Symbol declaration is inconsistent with a previous declaration at Ln/Cn. 
Tag name is being truncated to n characters in length. 

The rest of this line is extraneous. 

Toggle "name" is unrecognized. 

Toggle not recognizable. 

Toggle specifier must be an identifier. 

Too many arguments in "pragma Alias”. 

Too many arguments specified. 

Type "type" is not appropriate for a conditional expression. 


Type "typel" is not assignment compatible with type "type2". 


(a) In an assignment expression, the right operand of type typel may not be assigned 
to the left operand of type type2. (b) In a function call, an argument of the type 
typel may not be passed to a function that expects a parameter of type type2. 


Type "typel" is not compatible with the type "“type2". 


In a comparison, the left operand of type typel may not be compared with the right 
operand, of type type2. 
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Type "type" is not valid for a struct member. 

Type of entity is a yet undefined struct/union. 

Type of entity is an array of unknown length. 

typedef name may not be qualified with adjective. 
Unable to cast type "typel" to type "type2". 

Unable to determine the size of array type. 

Unable to initialize array; element type not complete. 
Undefined structure member. 

Unexpected character "c" follows "\". 

Unexpected symbol in expression. Line ignored. 

union tag was previously declared as a struct. 

union was previously defined as a struct. 

Unreachable statement. 

Unrecognizable data section class. 

Unrecognizable pragma directive or toggle: name(text) 
Unrecognizable pragma directive: name 

Unrecognizable pragma. 

Unrecognized preprocessor directive: "name". 

Unsigned compare with zero always false. 


Unsigned compare with zero always true. 


An expression of type unsigned int is never less than zero. Thus, a comparison to 
check whether the unsigned int expression is greater than zero will always be true, 
and a comparison to check if it is less than zero will always be false. 


Up-level reference to a register-class variable is not allowed. 


Value of escape sequence exceeds maximum value representable in unsigned 
char. 


Variable "name" is never referenced. 


Variable "name" is possibly referenced before set. 


This warning is issued by the optimizer when it has found an auto- or register- class 
variable that is “live” at its declaration. In other words, the compiler has detected a 
potential path in which such a variable is referenced prior to being assigned a value. 
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This condition is not necessarily an error in that the “potential” path may never 
occur. For example, the variable “x” in the following code fragment would be diag- 
nosed with this warning: 


static void foo(int i) { 
int x; 
if (i >= 0) x=1; 
1 (ie 0) ees 
printf ("x=%d\n",x); 
} 


Variable expected. 


In this context a so-called “Ivalue” is required but was not found. An lvalue is 
something whose address can be taken, and is required on the left side of an assign- 
ment expression and as an operand to &,++, and --. The rules of C require the 
automatic conversion of some objects into non-lvalues. For example, the operand of 
& must be an lvalue, so inti = &(a+b) produces the “Variable expected.” diag- 
nostic. A common cause of this message is the use of a construct such as: 


int * p; 
c= * (( char*)p)++; 


which is legal on most PCC compilers, but disallowed by the ANSI Standard. Use 
instead: 


At Ds 
c = *(* (char**)&p)++; 


to circumvent the restriction. This solution works only when p is not a register vari- 
able; unfortunately we know of no solution for register variables. 


Variable previously initialized at Ln/Cn. 

Variables within a user-specified data section must not be "extern". 
Variables within an imported data section must be "static". 

"void" is not a valid argument type. 


"volatile" qualifier in cast has no effect. 


The warning is issued to remind the user that simply casting a variable to a volatile 
type does not force the variable to be volatile. This is because the variable being cast 
is actually an rvalue. For example, the cast in the following assignment accom- 
plishes nothing: 


int a,b; 
a = (volatile int)b; 


The effect of forcing b to be volatile can be attained by the following sequence: 


a = *(volatile int *)&b; 
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Appendix B. ASCII Character Set 


This appendix lists the standard ASCII characters in numerical order with the corre- 
sponding decimal, octal, and hexadecimal values. The control characters are indi- 
cated by a Ctrl- notation. For example, the horizontal tab (HT) ts indicated by 
Ctrl-I, which is keyed by simultaneously pressing the Ctrl key and I key. 


Note that this character set was originally developed for teletype communications. 
Consequently, most of the original control characters (decimal 0 through 31) are 
undefined in other types of communication. However, two important control char- 
acters have retained their original function: LF (decimal 10), which generates a line 
feed (causing subsequent output on a display or printer to appear on the next line), 
and CR (decimal 13), which generates a carriage return. 


Table B-! (Page | of 5). ASCII Character Set 


Octal | Hex Control ASCII 
Value | Value | Character Symbol | Comment 


Ctrl-@ NUL null 

Ctrl-A SOH start of heading 
Ctrl-B STX start of text 
Ctrl-C ETX end of text 
Ctrl-D EO 
Ctrl-E ENQ 
Ctrl-F ACK 
07 07 Ctrl-G BEL 


Decimal 
Value 


8 


001 01 
002 02 
003 03 
004 04 
00 05 





end of transmission 


Dn 
op 


inquiry 
acknowledge 


bell 





KO bQ oman’ _— pend —— a _— a peeed poe — ~~] La a we) bho poe, om) 


010 08 Ctrl-H BS backspace 
0 | 09 | Coker | HT horizontal tab 
O12 |Bie line feed 

013 | 0B | CwlK — | VT vertical tab 
014 FF form feed 
O15 |0D | Cem | CR carriage return 
016 shift out 


peo 
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Table B-1 (Page 2 of 5). ASCII Character Set 
Octal | Hex | Control ASCII 
Value | Value | Character Symbol | Comment 
Ctrl-W ETB end of transmission 
| block 
CAN 


027 17 

Ctrl-X cancel 
Ctrl-Y EM 
Ctrl-Z SUB substitute 
Cirl{ ESC escape 
Ctrl-\ FS file separator 
Ctrl} group separator 
Ctrl-a RS | record separator | 
Ctrl-_ U 
SP 


Decimal 
Value 


bho 
7) 


030 
031 
032 


18 

19 

1A 
IB 
IC 
1D 
1E 
IF 


ho 
an 


KO 


No 
ON 


end of medium 


Pas 
28 
29 


Oo}; © 
to | OO 
& | WwW 


\o) 
we) 
_ 


aa 
w | uw No Nf} No 
N oo aie oN N 


\e°) 

an) 
a) 
eS) 
oa) 


036 
037 
04 


Go 
= 
Fp) 


Tre reyyyre 


unit separator 
3 
33 


KO 
om) 
i) 
—) 


space 


c> 
re 


1 
42 
043 
044 
04 
04 
04 
050 
051 
052 
053 
54 


poe 


os) 
B | 
oS 
ho 


ee) 
~N 
NO 
ee) 


oS) 
—~ 
CA 
No 
Sa) 


Ww 
(oe) 
ON 


oS) 
\O 


apostrophe 


AN 
© 
i) 
io 2) 


> 
— 
MN 
iw) 
\O 


aN 
NO 
bo 
> 


aN 
we) 
ho 
ee) 


. 
fs 
© 


Ny 
‘o) 


comma 


minus 


BS 
Ga 
S 
Wn 
~ 
o) 


> 
ON 


0 
057 
060 
061 


iw) 
ON 
NO 


period 


= 
CO 


ON 
ho 


49 
50 
5 


—" 


~ 
~) 
No 
Tj 


Nn 
we) 
eo ) Oo 
WN a) 


p—_— 


ON 
o>) 
1s) 
: 


ws 
to 


064 
065 


Nn 
Go 
BS 


—) 
ON 
~ 


55 


an 
; 
a) 
—] 
© 
o>) oe) WwW 
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Table 


Comment 


ASCII 
Symbol 
aoe 
Bcd 
CS ae 

< 


 . oe Se 


rs [ eS 
C7 [pw 
a 
—_ 


G 
H 
I 
J 
K 
L 
M 
N 
ro 
oa 
ro 
rR 
S 
ae ee 
a 


Hex Control 
Value | Character 
of 
a 
Bo 
3p | 
se | 
ce ee E 
ae 
ae 
ae 
oo | UF 
a 
‘sadnnemaiad 
cecal 
= 
ee 
Lssinainesl 
—_—e 
an 
ez 
| Sanaeceel 
einen 


45 
om 
4E 
4F 
50 
51 
52 
53 


Octal 
Value 
071 
072 


Decimal 
Value 
57 

58 


105 
116 
120 
122 
123 
131 

132 


0 
39 
90 
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Table 


Control ASCII | 
Character Symbol | Comment 
ee ee ee 


| 


— Ww) 
t™ t™ 


underscore 
grave accent 


C 
O 
r 


rs ee 


a a ee 
Vv 

ee a ee 

es ee 

mA 

mf tT 

i as Cae 


rc ff 
ro [fa 
re [de 


aw) mi w 

@ 
4 = 
oS eg eee gee —|alal|atlu ~ < mlo a} on | + No On 
— > MI Mm] ww ololwolwolvwo oO Ne) ole miei ne wa ~ 
32 

=| 
Ss imili itl ml olprel oleae nl mit l on] wolrns lL ola i Nini r~ALnI wool rml_ ai as I nimirinsy woyermrsli oly mL nitinit st 
YS BimMmlalainianl!l stig ilieti al stele tle lA L Nl nl nl Al L ni wvni ni Sliwolwolwol]lololoelol el rl rn etre 
Ce ie Page eee Weegee eee wl ose eee fl near cement sede aeeece| | age Wo eearge  eeng) A ceeety eb aes Ts octet ttl hee Me een eae nega ch oa, Mle ety a nce Leas fae Hs ely Ae cee I ge cee 
peed 
= 
Eg 
oS Dale lal al +t!l ni olrmilcwzw.lalolealslatlianitl ni wlrmlwlalo;la|ranlnie«z 
2S Si asp nti ani tl wn rm SlLolololalo!l sso SIS] slays] al alate el asp e~PALanIl alain 
SBS PrPI nl Il alalalia DN ee ee ee ne ee eee ee eee en eee ee ne ee ee a ee ee ee | 
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Fa 9 
Value Value | Value | Character Symbol | Comment 

ras fs [wm ff) | 
rias_fs [oe [| [~ | 
papa [e | ‘poet [ae 
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Appendix C. Program Examples for Mixing Languages 


The following sample programs show ways to connect program units written in dif- 
ferent languages. They also illustrate the mechanisms for passing character, integer, 
and floating-point variables between C, VS FORTRAN, and VS Pascal. 


In covering these three variable types, an example of each language calling the other 
languages is given. The sample programs are included only to illustrate the mixing 
of the languages and do not show all types of parameter passing. 


The list of commands needed to compile and run the sample programs are included 
with each sample. 


Note: On the RT PC, VS FORTRAN appends the underscore (_) character to 
external symbols; therefore, routines declared in C or VS Pascal will need to append 
an underscore to the names of routines called from or to VS FORTRAN. This does 
not apply to AIX/370. 


C Calling FORTRAN and Pascal 


© Copyright IBM Corp. 1989 


The Calling C Program 


/* This code is in the file named "cexam.c". */ 
#include <stdio.h> 


main () 

{ 
printf("\n This message is printed at the start of MAIN."); 
cfunc(); 
printf("\n This message is printed at the end of MAIN. \n") 
exit(0); 

} 


cfunc () 

{ 
char chrc[79]; 
int count, 1c; 
float xc; 
double yc; 


chrc[O] = 'h's chrc[1] = 'i's chrce[2] =' '; 
chrc[3] = 'C'; chrc[4] = '\0'; 

ic = 50; xc = 10.3; yc = 0.0; 

count=10; 


printf("\n \n \n Before calls:"); 
printf("\n Text string: %s", chrc); 
printf("\n ic = %d", ic); 
printf("\n xc = %f", xc); 
printf("\n yc = %f", yc); 


fsub (chrc,&ic,&xc,&yc,count) ; /* Arrays in C always use */ 
/* the call-by-reference */ 
/* mechanism. a 


printf("\n \n After FORTRAN call:"); 
printf("\n Text string: %s", chrc); 
printf("\n ic = %d", ic); 
printf("\n xc = %f", xc); 
printf("\n ye = %f", yc); 
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psub(chrc,&ic,&xc, &yc) ; 

printf("\n \n After Pascal call:"); 
printf("\n Text string: %s", chrc); 
printf("\n ic = %d", ic); 
printf("\n xc = %f", xc); 
printf("\n yc = %f \n", yc); 

} 


Note: On the RT PC, the call to the procedure fsub must include the underscore (_) 
character appended to its name; that 1s, fsub_. 


The Called FORTRAN Subroutine 
C This is the FORTRAN subroutine to be called by C. 
C This code is in the file named "ccallf.f". 


SUBROUTINE FSUB(WORDS,1,X,Y) 
CHARACTER*80 WORDS 
INTEGER I 
REAL X 
DOUBLE PRECISION Y 
C The string terminator C expects is concatenated. 
WORDS='FORTRAN lives! '//CHAR(Q) 
I=L0G(X) 
X=LOG(X) 
Y¥=45.D0 
RETURN 
END 


The Called Pascal Procedure 
{ This is the Pascal procedure to be called by C. 
This code is in the file named "ccallp.p". } 


segment DUMMYNAME; 


type TEXT = packed array [0..79] of CHAR; 


procedure PSUB (var WORDS : TEXT; 
var | : INTEGER; 
var X > SHORTREAL; 
var Y : REAL ); external; 


procedure PSUB; 
begin 


WORDS[0] := 'G'; WORDS[1] := 'o'; WORDS[2] :=' ' ; 
WORDS[3] := ‘W's WORDS[4] := 'i'; WORDS[5] := 'r' ; 
WORDS[6] := 't's WORDS[7] := 'h'; WORDS[8] := ‘'!' ; 


WORDS [9] : 

X := 2*X; 

I := 2*1; 

Y := 4.0d0; 
ends; 


chr(0); { C character string terminator } 
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Commands and Output 


The commands needed to compile and run this sample program on the PS/2 are: 


cc -0 
cexam 


cexam cexam.c ccallf.f ccallp.p 


The commands needed to compile and run this sample program on the RT are: 


VS -O 
cexam 


cexam cexam.c ccallf.f ccallp.p 


The output from running this sample program Is: 


This message is printed at the start of main. 


Before calls: 


Text 
ic = 
XC = 
yc = 


After 
Text 
ic = 
XC 
yc = 


After 
Text 
ic = 
XC 
yc = 


string: hi C 
50 

10.000000 
0.000000 


FORTRAN call: 
string: FORTRAN lives! 
2 


= 2.302585 


45.000000 


Pascal call: 
string: Go Wirth! 
4 


= 4.605170 


4.000000 


This message is printed at the end of main. 


FORTRAN Calling Pascal and C 
The Calling FORTRAN Program 


C 
C 


100 


This FORTRAN code is in the file named "forexam.f". 


PROGRAM EXAMPLE 

CALL MYCHOICE 

WRITE(*,100) 

FORMAT(/' I''ve safely returned after doing all that!') 
END 


SUBROUTINE MYCHOICE 
INTEGER IFOR 

INTEGER COUNT 

REAL XFOR 

DOUBLE PRECISION YFOR 
CHARACTER*10 CHRFOR 
CHARACTER*5 CHRFIVE 
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C Some data is initialized. 
EQUIVALENCE (CHRFOR,LETTER) 
CHRFOR='HELLO' 
CHRFIVE='AGAIN' 

IFOR=50 
COUNT=10 
XFOR=10 
YFOR=0. 


WRITE(*,100) CHRFOR, IFOR,XFOR,CHRFIVE,YFOR 
100 FORMAT(/'Before calls:'/' IFOR='I10/' Text string: *'A'*! 
+ ' XFOR='F10.2/' Text string: *'A'*'/' YFOR='F10.2) 


C A Pascal procedure is called. 


CALL PSUB(IFOR, CHRFOR, XFOR, CHRFIVE, YFOR) 
WRITE(*,110) IFOR,CHRFOR,XFOR,CHRFIVE,YFOR 
110 FORMAT(/'After Pascal call:'/' IFOR='1I10/' Text string: *'A'*' 
+ ' XFOR='F10.2/' Text string: *'A'*'/' YFOR='F10.2) 


C A C subroutine is called. 


CALL CSUB(IFOR, CHRFOR, XFOR, CHRFIVE, YFOR) 
WRITE(*,120) IFOR,CHRFOR,XFOR,CHRFIVE,YFOR 
120 FORMAT(/'After C call:'/' IFOR='I10/' Text string: *'A'*' 
+ ' XFOR='F10.2/' Text string: *'A'*/' YFOR='F10.2) 


END 
The Called Pascal Procedure 


{ This is the Pascal procedure to be called by FORTRAN. 
This code is in the file named "“fcallp.p". } 


segment DUMMYNAME; 


type TEXT = packed array [0..79] of CHAR; 


{ Note that the incoming arguments which were passed 
as FORTRAN characters arrive as pointers in their 
actual locations, with their lengths, in order, at 
the end of the argument list. } 


procedure PSUB (var I 
var WORD1 
var X 


var WORD2 : 
: REAL; 

: INTEGER; 

: INTEGER) ;external; 


var Y 
LEN1 
LEN2 
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: INTEGER; 
: TEXT; 
: SHORTREAL; 


TEXT; 


procedure PSUB ; 
var J : INTEGER; 
begin 
WORD1[0] := 'B'; WORD1[1] := 'Y'; WORD1[2] := 'E'; 
FOR J := 3 TO LENI-1 DO 
WORDI[J] :=' '; 


FOR J := 0 TO LEN2-1 DO 
WORD2[J] := 'P'; 

X:=X * T3 

I := LEN1; 

Y := 1.0d0; 

end; 


Note: On the RT PC, the external declaration and definition for procedure PSUB 
must include the underscore (_) character appended to its name; PSUB_. 


The Called C Function 


Note: 


/* This is the C function to be called by FORTRAN. * / 
/* This code is in the file named "fcallc.c". * | 


void csub ( i, 
wordl, 
Ks 
word2, 
Ys 
lenl, /* Note the hidden length arguments corresponding */ 
len2) /* to wordl and word2 */ 


char word1[79],word2[79]; 
int. *13 

int lenl,len2; 

float *x; 

double *y; 


{ 
int j; 


word1[0] 

word1[1] 

wordl[2] = ' '; 

wordl[{3] = 'C'; 

for (j=4; j<lenl-1; j++) 
wordl[j] = ' '; 


*] = -3; 
*x = -(*x); 
*y = 2.0; 
word2[0] 
word2 [1] 
word2 [2 | 
word2[3] = 
word2 [4] 


“hes /* Arrays in C always use the */ 
ue /* call-by-reference mechanism. */ 


WoW on 
- - - _ - 
we we wee we wo 


m5 07 M3 


On the RT PC, the definition of the function csub must include the under- 


score (_) character appended to its name; csub_. 
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Commands and Output 


The commands needed to compile and run this sample program on the PS/2 are: 


cc -o forexam forexam.f fcallp.p fcallc.c 


forexam 


‘The commands needed to compile and run this sample program on the RT are: 


vs -o forexam forexam.f fcallp.p fcallc.c 


forexam 


The output from running this sample program is: 


Before calls: 

IFOR= 50 

Text string: *HELLO 
Text string: *AGAIN* 
YFOR= .00 


After Pascal call: 
TFOR= 10 
Text string: *BYE 
Text string: *PPPPP* 
YFOR= 1.00 


After C call: 
IFOR= -3 
Text string: *hi C 
Text string: *CLong* 
YFOR= 2.00 


* XFOR= 


* XFOR= 


* XFOR= 


10.00 


500.00 


-500.00 


I've safely returned after doing all that! 


Pascal Calling FORTRAN and C 
The Calling Pascal Program 


{ This code is in the file named "“pasexam.p". } 


program MAIN (input,output) ; 
type TEXT = packed array [0..79] of CHAR; 


procedure FSUB (var 
var 
var 
var 


procedure CSUB ( 
var 
var 
var 
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NAMES : 
IPAS 
XPAS 
YPAS 
LEN1 


NAMES : 
IPAS 
XPAS 
YPAS 


TEXT 


>: INTEGER; 

: SHORTREAL; 

>: REAL; 

: INTEGER ); external; 


TEXT 


: INTEGER; 
: SHORTREAL; 
: REAL ); external; 


procedure PSUB; 

var 
CHRPAS : TEXT; 
INTPAS : INTEGER; 
XREAL : SHORTREAL; 
YDOUB : REAL; 


I : INTEGER; 
begin 
CHRPAS[O] := 'H'; CHRPAS[1] := 'I'; CHRPAS[2] := ' '; 
CHRPAS[3] := 'W'; CHRPAS[4] := ‘I'; CHRPAS[5] := 'R'; 
CHRPAS[6] := 'T'; CHRPAS[7] := 'H'; 
INTPAS = 50; 
XREAL = 10.0; 
YDOUB = 0.0d0; 
writeln; 


writeln ('Before calls:'); 

write(' Text: *'); for I := 0 to 7 do write(CHRPAS[I]); 
writeIn('*'); 

writeln(' INTPAS=',INTPAS:2,' XREAL=',XREAL,' YDOUB=',YDOUB); 
FSUB (CHRPAS, INTPAS,XREAL, YDOUB, 20) ; 


writeln; 

writelIn (‘After FORTRAN call:'); 

write(' Text: *'); for I := 0 to 20 do write(CHRPAS[I]); 
writeln('*')s; | 

writeln(' INTPAS=',INTPAS:2,' XREAL=',XREAL,' YDOUB=',YDOUB); 
CSUB(CHRPAS , INTPAS,XREAL, YDOUB) ; 


writeln; 
writeln (‘After C call:'); 
write(' Text: *'); for I := 0 to 4 do write(CHRPAS[I]); 
writeln('*'); 
writeln(' INTPAS=',INTPAS:2,' XREAL=',XREAL,' YDOUB=',YDOUB) ; 
writeln; 

end; 


begin 

writeln('This message is printed at the beginning of MAIN.'); 
PSUB; 

writeln('This message is printed at the end of MAIN.'); 
end. 


Note: On the RT PC, the external declaration and call to the procedure FSUB must 
include the underscore (_) character appended to its name; FSUB_. 
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The Cailed FORTRAN Subroutine 
C This is the 
C 


FORTRAN subroutine to be called by Pascal. 


This code is in the file named "pcallf.f". 


SUBROUTINE FSUB(CHR,1I,X,Y) 
CHARACTER*20 CHR 


INTEGER I 
REAL X 


DOUBLE PRECISION Y 


I=LEN (CHR) 


CHR='FORTRAN Lives!' 


X=X* I 
Y=1.0D0 
RETURN 
END 


The Called C Function 


i 
| ia 


int csub (word, 
Ls 
Xy 
y) 


char word[79]; 
int “15 

float *x; 
double *y; 


{ 
word[0] = 
word[1] 
word[2 | 
word[3] 
word[4] 


= 3; 
*x = -1.0; 
*y 1.0; 
return(Q); 


~ 
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This is the C function to be called by Pascal. 
This code is in the file named "pcallc.c". 


a 
*/ 


/* Arrays in C always use the */ 
/* call-by-reference mechanism. */ 


Commands and Output 


The commands needed to compile and run this sample program on the PS/2 are: 
cc -O pasexam pasexam.p pcallf.f pcallc.c 
pasexam 

The commands needed to compile and run this sample program on the RT PC are: 
vS -O pasexam pasexam.p pcallf.f pcallc.c 
pasexam 

The output from running this sample program 1s: 
This message is printed at the beginning of MAIN. 
Before calls: 


Text: *HI WIRTH* 
INTPAS=50 XREAL= 1.0000000000000E+01 YDOUB= 0.0000000000000E+000 


After FORTRAN call: 
Text: *FORTRAN lives! * 
INTPAS=20 XREAL= 2.0000000000000E+02 YDOUB= 1.0000000000000E+000 


After C call: 
Text= *hi C * 
INTPAS=-3 XREAL=-1.0Q000000000000E+00 YDOUB= 1.0000000000000E+000 


This message is printed at the end of MAIN. 
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370 


PREPROCESSOR STATEMENTS 


nesting levels for include files 
macro identifiers defined in a file 
arguments in one macro invocation 


IDENTIFIERS 


significant chars in an internal identifier 
significant chars in an external identifier 
external identifiers declared in a file 
block-scope identifiers in one block 


DECLARATORS 


variables in a single declaration 
enumeration constants 

members in a structure or union 
initialization elements 

nesting levels of structure or unions 
characters in a string literal 


STATEMENTS 


case labels for a switch statement 


FUNCTIONS 


Note: 


parameters in one function definition 
arguments in one function call 


PS/2 


31? 


%¥ %*%*§ %€ 


* 4+ * %X% %%& 


RT 


31 


64 
64 


¥ %* %X%+ %X 


327677 


PC 


64 
64 


*¥ %F %XF F FX 


2000 


‘This means that in preprocessor statements, arguments in one macro invocation 
are limited to 31, but not limited in the C inboard cpp. 


?This includes the null character. 


3The item is not explicitly limited by the C Compiler. 
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